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PREFACE 


About This Book 


This book, Inside Macintosh: Macintosh Toolbox Essentials, describes the essential 
elements of a Macintosh application and the system software routines that 
you can use to implement them. 


If you are new to programming on the Macintosh computer, you should also 
read Inside Macintosh: Overview for an introduction to general concepts of 
Macintosh programming and Macintosh Human Interface Guidelines for a 
complete discussion of user interface guidelines and principles that every 
Macintosh application should follow. 


This book describes events, windows, menus, controls, alert boxes, and dialog 
boxes. It also discusses how your application interacts with the Finder. 


Macintosh applications respond to user actions and to other hardware- and 
software-related events. To design your application so that it can respond to 
events (such as keyboard input, mouse input, changes in the appearance of 
windows on the screen, and changes in your application’s processing status), 
see the chapter “Event Manager” in this book. 


To create menus and set up your application’s menu bar, see the chapter 
“Menu Manager.” This chapter describes how to define the items in your 
menus, how to enable and disable menus, how to allow the user to choose 
a menu item, and how to respond once the user chooses a menu item. 


To create windows in which the user can view or edit information, see the 
chapter “Window Manager.” This chapter describes the basic types of 
windows and discusses how your application can work together with the 
Window Manager to support the standard user interface conventions 
associated with manipulating a window, such as moving a window, zooming 
a window, and resizing a window. 


To create controls in your application’s windows—such as scroll bars—or to 
create controls in dialog boxes—such as buttons or checkboxes—see the 
chapter “Control Manager.” 


To create dialog boxes or alert boxes—windows that your application uses to 
communicate with or solicit information from the user—see the chapter 
“Dialog Manager.” 


To create icons for your applications and the documents it creates, see the 
chapter “Finder Interface.” This chapter also introduces file types and 
creators and describes the various kinds of resources (icons, file references, 
and bundles) that the Finder needs to display your application and the 
documents it creates. 


After implementing the basic elements of a Macintosh application as 
described in this book, you can add additional features, such as help balloons 
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and support for copy and paste, as described in Inside Macintosh: More 
Macintosh Toolbox. You can also find detailed information about the Resource 
Manager in Inside Macintosh: More Macintosh Toolbox. 


Once you understand how to create menus, windows, and dialog boxes, you 
can save information that the user enters in a window by writing the data to a 
file. You can also open a previously saved file and read the information from 
the file into a window. You use the File Manager to open, read, write, and 
close files. See the chapter “Introduction to File Management” in Inside 
Macintosh: Files for information on how to read and write files. 


For information about drawing into a window or other graphics port, see 
Inside Macintosh: Imaging. 


For information on handling text in your application, see Inside 
Macintosh: Text. 


For information on communicating with other applications, see Inside 
Macintosh: Interapplication Communication. 


Format of a Typical Chapter 


Almost all chapters in this book follow a standard structure. For example, the 
Event Manager chapter contains these sections: 


a “Introduction to Events.” This section presents a general introduction to 
the types of events that your application can receive. 


mw “About the Event Manager.” This section provides an overview of the 
features provided by the Event Manager. 


m “Using the Event Manager.” This section describes the tasks you can 
accomplish using the Event Manager. It describes how to use the most 
common routines, gives related user interface information, provides code 
samples, and supplies additional information. 


gm “Event Manager Reference.” This section provides a complete reference 
to the Event Manager by describing the data structures, routines, and 
resources it uses. Each routine description also follows a standard format, 
which presents the routine declaration followed by a description of every 
parameter of the routine. Some routine descriptions also give additional 
descriptive information, such as assembly-language information or 
result codes. 

a “Summary of the Event Manager.” This section provides the Pascal and 
C interfaces for the constants, data structures, routines, and result codes 
associated with the Event Manager. It also includes relevant assembly- 
language interface information. 


Conventions Used in This Book 


Inside Macintosh uses various conventions to present information. Words that 
require special treatment appear in specific fonts or font styles. Certain 
information, such as the contents of registers, use special formats so that you 
can scan them quickly. 
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Special Fonts 


All code listings, reserved words, and names of actual data structures, 
fields, constants, parameters, and routines are shown in Courier (this 
is Courier). 


Words that appear in boldface are key terms or concepts and are defined in 
the Glossary. 


Types of Notes 


There are several types of notes used in this book. 


Note 


A note like this contains information that is interesting but possibly not 
essential to an understanding of the main text. (An example appears on 
page 2-7.) @ 


IMPORTANT 


A note like this contains information that is essential for an 
understanding of the main text. (An example appears on page 5-27.) & 


WARNING 


Warnings like this indicate potential problems that you should be aware 
of as you design your application. Failure to heed these warnings could 
result in system crashes or loss of data. (An example appears on page 
page 2-105.) & 


Empty Strings 


This book occasionally instructs you to provide an empty string in routine 
parameters and resources. How you specify an empty string depends on what 
language and development environment you are using. In Rez input files and 
in C code, for example, you specify an empty string by using two double 
quotation marks ('""), and in Pascal you specify an empty string by using two 
single quotation marks ("). 


Assembly-Language Information 


Inside Macintosh provides information about the registers for specific routines 
like this: 


Registers on entry 
AO Contents of register AO on entry 


Registers on exit 


DO Contents of register DO on exit 
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In the “Assembly-Language Summary” section at the end of each chapter, 
Inside Macintosh presents information about the fields of data structures in 
this format: 


0 what word event code 
2 message long event message 
6 when long ticks since startup 


The left column indicates the byte offset of the field from the beginning of the 
data structure. The second column shows the field name as defined in the 
MPW Pascal interface files; the third column indicates the size of that field. 
The fourth column provides a brief description of the use of the field. For a 
complete description of each field, see the discussion of the data structure in 
the reference section of the chapter. 


The Development Environment 


The system software routines described in this book are available using 
Pascal, C, or assembly-language interfaces. How you access these routines 
depends on the development environment you are using. When showing 
system software routines, this book uses the Pascal interface available with 
the Macintosh Programmer’s Workshop (MPW). 


All code listings in this book are shown in Pascal (except for listings that 
describe resources, which are shown in Rez-input format). They show 
methods of using various routines and illustrate techniques for accomplishing 
particular tasks. All code listings have been compiled and, in many cases, 
tested. However, Apple Computer, Inc., does not intend for you to use these 
code samples in your application. You can find the location of code listings in 
the list of figures, tables, and listings. If you know the name of a particular 
routine (such as DoEvent or MyAdjustMenus) shown in a code listing, you 
can find the page on which the routine occurs by looking under the entry 
“sample routines” in the index of this book. 


In order to make the code listings in this book more readable, they show only 
limited error handling. You need to develop your own techniques for 
handling errors. 


This book occasionally illustrates concepts by reference to a sample 
application called SurfWriter; this is not an actual product of Apple 
Computer, Inc. 


APDA is Apple’s worldwide source for over three hundred development 
tools, technical resources, training products, and information for anyone 
interested in developing applications on Apple platforms. Customers receive 
the quarterly APDA Tools Catalog featuring all current versions of Apple and 
the most popular third-party development tools. Ordering is easy; there are 
no membership fees, and application forms are not required for most 
products. APDA offers convenient payment and shipping options including 
site licensing. 
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To order products or to request a complimentary copy of the APDA Tools 
Catalog, contact: 


APDA 

Apple Computer, Inc. 
P.O. Box 319 

Buffalo, NY 14207-0319 


Telephone: 800-282-2732 (United States) 
800-637-0029 (Canada) 
716-871-6555 (elsewhere in the world) 


Fax: 716-871-6511 


If you provide commercial products and services, call 408-974-4897 for 
information on the developer support programs available from Apple. 


For information on registering signatures, file types, Apple events, and other 
technical information, contact 


Macintosh Developer Technical Support 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 75-3T 
Cupertino, CA 95014-6299 
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CHAPTER 1 


Introduction to the Macintosh Toolbox 


This chapter presents an introduction to the features provided by the Macintosh 
Toolbox. The Macintosh Toolbox is a collection of system software routines that your 
application can use to present a consistent and standard interface to the user; these 


routines also allow you to simplify other tasks your application might need to perform. 


A typical Macintosh application presents a friendly, intuitive, easy-to-use, visual inter- 
face to the user. The careful design of a Macintosh application gives users the freedom 
to perform actions and accomplish tasks according to their needs. The idea behind this 
careful design is to put the user in control. In general, the user of a Macintosh applica- 
tion should always be free to choose the next action he or she will perform. (This is the 


basic tenet of the event loop and is explained in more detail in the chapter “Event Manag- 


er” in this book.) 


Figure 1-1 shows the screen as it might appear when a user is interacting with a typical 


Macintosh application, such as SurfWriter. The SurfWriter application is an application 
that lets a user do simple text editing. Like most Macintosh applications, the SurfWriter 


application uses 


m menus to let the user choose commands 


m windows to allow the user to enter and edit information 


= scroll bars to allow the user to view more information in a window 


Figure 1-1 The SurfWriter application with multiple windows on the desktop 
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m other controls (such as the Change button) to let the user control various settings 
or options 


m dialog boxes to solicit information from the user 


You can create an application that incorporates these user-interface elements and that 
helps users accomplish specific tasks by taking advantage of the routines provided by 
the Macintosh Toolbox. 


Overview of the Macintosh Toolbox 


Macintosh system software contains a powerful set of routines that your application can 
use to create windows, manage menus, paint objects, display text, open files, share data 
between programs, and print files, as well as perform many other helpful tasks. 


The Macintosh Toolbox encompasses a number of system software routines, most (but 
not all) of which help present your application’s interface to the user. Some of these 
routines include those provided by the Event Manager, Menu Manager, Window 
Manager, Control Manager, Dialog Manager, Help Manager, Resource Manager, and 
Scrap Manager. 


You can directly call these routines from within your application. By using system 
software routines, you can take advantage of the many tasks they can perform for 
you, and you can concentrate on the parts of your application that are specific to 
your particular product. 


Using the Macintosh Toolbox, you can 

m respond to user actions, such as mouse actions or keyboard input 

m create and display menus 

m create and display windows, alert boxes, and dialog boxes 

m create and display controls in windows, alert boxes, and dialog boxes 
m create icons for your application and its documents 


This book, Macintosh Toolbox Essentials, describes these fundamental elements of a 
Macintosh application. Inside Macintosh: More Macintosh Toolbox describes additional 
features of a Macintosh application, including how you can 


m create help balloons for your application’s menus, windows, and dialog boxes 
m™ support copy and paste 


m specify characteristics of your application’s menus, windows, controls, dialog boxes, 
and help balloons in resources so that you can more easily localize your application 
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The best Macintosh applications are designed according to the guidelines in Macintosh 
Human Interface Guidelines. You should always design your application so that it meets 
the needs of its users and responds in consistent and expected ways. Macintosh Human 
Interface Guidelines describes 


m the philosophy and the design principles behind the Macintosh interface 
m the parts of the Macintosh interface including the interface elements and behaviors 
m ways to do human interface design for Macintosh products 


You can often get valuable feedback on the design of your application by performing 
user testing. Do usability testing of your application early and often in the development 
phase of your product. 


Events 


At the core of every Macintosh application is the application’s event loop. The event loop 
is that piece of code in an application that processes and responds to user actions and 
other events. You can use the Event Manager to retrieve information about these actions. 
For example, you can get information that tells your application whether the user 
pressed a key or the mouse button, whether one of your application’s windows needs 
updating as a result of the user moving windows, or whether some other hardware or 
software action requires a response from your application. 


You should structure your application so that it can respond to events and so that the 
user is able to perform tasks in any order. For example, a user should be able to type text 
in a window, select a graphic and copy it, open a new document, paste in the graphic, 
open another document, and then go back to the first window to select text and change 
its typeface, size, or style. 


Your application should respond to events in a way that lets the user switch between 
your application and others whenever the user chooses to do so (for example, by clicking 
in a window belonging to another application). Your application should also yield time 
to other applications when it isn’t busy. System software provides a cooperative 
multitasking environment that allows users to switch between many open applications 
and that allows applications to receive available processing time when other applications 
aren’t using the processor. System software coordinates the scheduling of processing 
time between your application and other applications. 


You can also let your application communicate with other applications in order to 
request services or information from another application or to provide services to other 
applications. You can use the Event Manager or Apple Event Manager to do this. 


The chapter “Event Manager” in this book describes how to structure your event loop 
and event-handling code to receive notification of user actions and changes in the 
processing status of your application, how to communicate with other applications, and 
how to respond to these events. 
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Menus 


Menus are an important part of the design of a Macintosh application. Menus let users 
view or choose an item from a list of choices or commands that your application 
provides. You design your menus according to the tasks or actions your application 
performs. All applications should support the Apple, File, Edit, Help, Keyboard, and 
Application menus. Figure 1-1 on page 1-3 shows the File menu of the SurfWriter 
application. 


System software makes it easy for you to create pull-down, hierarchical, and pop-up 
menus. The chapter “Menu Manager” in this book describes how to create your 
application’s menus, set up your menu bar, display menus, and respond to the user’s 
choice of an item from a menu. 


Windows 


Most applications interact with the user through windows. Figure 1-2 shows a common 
window and its elements. The chapter “Window Manager” in this book describes the 
types of windows your application can create and how to respond to user actions 
involving windows. 


Figure 1-2 A typical window 
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The user typically has one or more windows on the desktop, often from a number of 
different applications. Although the user can have multiple windows on the desktop, 
only one window is the active window. The active window is the window that appears 
frontmost on the desktop and is identified by racing stripes in its title bar. Figure 1-2 
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shows an active window; in Figure 1-1 on page 1-3, the window titled SalesReport is an 
inactive window. 


All keyboard activity is directed toward the active window. You should make sure that 
your application follows the human interface guidelines regarding active and inactive 
windows. For example, you should show the scroll bars and highlight any selection in 
an active window belonging to your application; you should hide the scroll bars and 
remove highlighting from any selection in an inactive window belonging to your 
application. The menu bar of your application also should always reflect the state of 
your application’s active window—that is, your application should enable only those 
menu commands that pertain to the active window. 


You can use system software routines to assist you when your application needs to 
create, move, size, Zoom, or update the contents of your window. The chapter “Window 
Manager” in this book describes how you can accomplish these tasks. 


Controls 


Most windows and dialog boxes contain controls. Controls are onscreen objects that the 
user can manipulate with the mouse to cause an immediate action from your application 
or to change settings in order to modify a future action. 


Buttons, checkboxes, radio buttons, pop-up menus, and scroll bars are examples of 
common controls used by most applications. Checkboxes, radio buttons, and pop-up 
menus are most often used in dialog boxes; buttons are most often used in alert boxes or 
dialog boxes; scroll bars are most often used in windows. Figure 1-3 illustrates these 
types of controls. 


Figure 1-3 Common controls 
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A button appears as a rounded rectangle with a title centered inside. Use a button to 
perform an instantaneous action when the user clicks the button, such as completing 
operations defined by a dialog box or acknowledging an error message in an alert box. 


A checkbox appears as a small square with a title beside it; the box contains an X when 
the setting associated with the box is on and is empty when the setting is off. Use a 
checkbox to indicate an option that must be either off or on. 


A radio button appears as a circle with a title beside it; the circle contains a small black 
dot when the setting associated with the radio button is on and is empty when the 
setting is off. Radio buttons are similar to checkboxes in that they retain and display 
an on-or-off setting; however, only one radio button in a group of radio buttons should 
be on at any one time. You must decide how to group your radio buttons, and your 
application must ensure that only one radio button in a group is on. 


A pop-up menu is a menu that appears in a dialog box or window. You can use pop-up 
menus as an alternative to radio buttons, to allow the user to select from a list of choices 
or settings. 


A scroll bar appears as a light gray rectangle that has scroll arrows at each end of the 
rectangle. A window can have a horizontal scroll bar, a vertical scroll bar, or both. You 
can use scroll bars to let the user change the portion of a document that the user can 
view within a window. 


You can track and respond to user actions in controls, redraw controls, and manipulate 
controls using Control Manager routines. You usually use the Dialog Manager to handle 
most controls in dialog boxes or alert boxes for you. The chapter “Control Manager” in 
this book describes how to create controls (with special emphasis on creating and using 
scroll bars in windows), and the chapter “Dialog Manager” in this book provides 
additional information about how to create controls in dialog boxes and alert boxes. 


Alert Boxes and Dialog Boxes 


In addition to standard windows, your application typically also uses alert boxes and 
dialog boxes. An alert box is a window that your application displays on the screen to 
warn the user or to report an error to the user. An alert box typically consists of text 
describing the situation and buttons for the user to acknowledge or rectify the problem. 
Figure 1-4 shows an alert box that the SurfWriter application displays when the user 
attempts to close a window without saving the document. The alert box gives the user a 
chance to save the document before the SurfWriter application closes the window; this 
prevents the user from accidentally losing data. 


Figure 1-4 An alert box 
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A dialog box is a window that you can use for the specific purpose of soliciting 
additional information from the user. The Dialog Manager provides routines to help you 
display dialog boxes and provides standard and consistent methods of interacting with 
the user. Dialog boxes can contain editable text items, informative or instructional text, 
and controls such as buttons and checkboxes. You can create modal, movable modal, or 
modeless dialog boxes. Figure 1-5 shows an example of each type of dialog box. 


A modal dialog box is a dialog box that puts the user in the state or “mode” of being able 
to work only inside the dialog box. A modal dialog box is similar in appearance to an 
alert box, except that a modal dialog box can contain editable text items and additional 


Figure 1-5 Modal, movable modal, and modeless dialog boxes 
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controls, such as radio buttons and pop-up menus. The user cannot move a modal dialog 
box, and the user can dismiss a modal dialog box only by clicking its buttons. You 
should use a modal dialog box only when it’s essential for the user to complete an 
operation before performing any other work. 


A movable modal dialog box is a modal dialog box with a title bar (but no close box) that 
allows the user to move the dialog box. The user can dismiss the dialog box only by 
clicking its buttons; however, when you use movable modal dialog boxes, you should 
allow the user to switch to another application if the user clicks in the window of 
another application or chooses another application from the Apple or Application menu. 
Use a movable modal dialog box when the user might need to move the dialog box to 
view other areas of the screen or when the user can switch to another application 
without affecting the state of your application. 


A modeless dialog box is a dialog box that looks like a document window without a size 
box or scroll bars. A modeless dialog box does not require the user to respond before 
doing anything else. The user can move a modeless dialog box, move between a 
modeless dialog box and other windows, and close a modeless dialog box just like a 
document window. Whenever possible, use a modeless dialog box instead of a movable 
modal or modal dialog box. Use a modeless dialog box when the user can perform other 
operations—such as working in document windows—without dismissing the modeless 
dialog box. 


The chapter “Dialog Manager” in this book describes in detail how you can create alert 
boxes and dialog boxes for your application. 


Icons and Other Interactions With the Finder 


Once you've designed your application, you need to create icons to represent the 
application and the documents it creates. The Finder displays these icons to the 
user. If your application appears as an item in the Apple or Application menu, the 
Menu Manager displays your application’s icon next to its name, and the Menu 
Manager displays your application’s icon as the title of the Application menu when 
your application is the active application. 


The chapter “Finder Interface” in this book describes how to define and create the icons 
for your application and its documents. The chapter also describes how your application 
interacts with the Finder. 


When a user opens your application or opens or prints one of its documents, the Finder 
uses the Process Manager to schedule your application for execution and then sets up 
the information your application needs to determine which, if any, files to open or print. 
In System 7, your application can choose to receive this information through Apple 
events. By supporting these and other Apple events, your application can efficiently 
respond to requests from the user as well as requests from other applications. See 

Inside Macintosh: Interapplication Communication for information about supporting 

Apple events. 
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Resources 


Resources are basic elements of every Macintosh application. By defining descriptions of 
menus, windows, controls, dialog boxes, sounds, fonts, and icons in resources, you can 
make these and other elements easier to create and manage. Using resources also eases 
translation of user interface elements into other languages. 


A resource is any data stored according to a defined structure in the resource fork of 

a file; the data in a resource is interpreted according to its resource type. You usually 
create resources using a resource compiler or resource editor. This book shows resources 
in Rez format; Rez is a resource compiler provided with the Macintosh Programmer’s 
Workshop (available from APDA). You can also use other resource tools, such as ResEdit 
(also available from APDA), to create the resources for your application. 


Most of the managers described in this book use the Resource Manager to read resources 
for you. For example, you can use the Menu Manager, Window Manager, Dialog 
Manager, and Control Manager to read descriptions of your application’s menus, 
windows, dialog boxes, and controls from resources. These managers all interpret a 
resource’s data accordingly once it is read into memory. While you'll typically use these 
managers to access resources for you, you can also directly use the Resource Manager 

to read and write resources. 


The chapter “Resource Manager” in Inside Macintosh: More Macintosh Toolbox describes 
the Resource Manager in detail. However, to help you understand how the Menu 
Manager, Window Manager, Dialog Manager, and Control Manager use resources, this 
section gives a brief overview of resources and provides a general introduction to the 
Resource Manager. 


Macintosh system software treats a file as a named, ordered sequence of bytes stored 
on a Macintosh volume and divided into two forks, the data fork and the resource fork. 
The data fork contains data that usually corresponds to data created by the user; the 
application creating the file can store and interpret the data in the data fork in whatever 
manner is appropriate. The resource fork of a file consists of a resource map and the 
resources themselves. 


When you write data to a file, you write to either the file’s resource fork or its data fork. 
You typically read from and write to a file’s data fork using File Manager routines and 
read from and write to a file’s resource fork using Resource Manager routines. 


You typically store as resources data that has a defined structure—such as icons and 
sounds—and descriptions of menus, controls, dialog boxes, and windows. When you 
create a resource, you assign it a resource type and resource ID. A resource type is a 
sequence of four characters that uniquely identifies a specific type of resource, and a 
resource ID identifies by number a specific resource within that type. (You can also 
use a resource name in place of a resource ID to identify a particular resource within a 
resource type.) For example, to create a description of a menu in a resource, you create 
a resource of type 'MENU' and give it a resource ID or resource name that is unique 
from any other 'MENU' resources that you have defined. Some resources have 
restrictions on the numbers you can use for resource IDs; in general, numbers 128 
through 32767 are available for your use. 
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System software defines a number of standard resource types, such as 'ALRT', 'CNTL', 
"CODE', 'DITL', 'DLOG', 'FONT', 'ICN#', 'ICON', 'MBAR', 'MENU', 'STR ', 
'STR#', and 'WIND'. You can use these resource types to define their corresponding 
elements (for example, use a 'WIND' resource to define a window). You can also create 
your own resource types if your application needs resources other than the standard 
resource types defined by the system software. 








The Resource Manager does not interpret the format of an individual resource type. 
When you request a resource of a particular type with a given resource ID, the Resource 
Manager looks for the specified resource and, if it finds it, reads the resource into 
memory and returns a handle to it. Your application or other system software routines 
can use the Resource Manager to read resources into memory. For example, when you 
use the Window Manager to read a description of a window from a 'WIND' resource, 
the Window Manager uses the Resource Manager to read the resource into memory. 
Once the resource is in memory, the Window Manager interprets the resource’s data and 
creates a window with the characteristics described by the resource. 


System software stores certain resources used by the system software in the System 
file. Although many of these resources are used only by the system software, your 
application can access some of these resources if needed. For example, the standard 
images for the I-beam and wristwatch cursors are stored as resources of type 'CURS' 
in the System file. You can use these resources to change the appearance of the cursor 
used by your application. 


Occasionally you may need to write resources to the resource fork of a file. For example, 
if your application saves the last position and size of a window (as determined by 

the user), you can store this information in the resource fork of the document in a 
resource defined by your application. The next time the user opens the document, your 
application can read the location saved in this resource and position the document 
accordingly. 


You typically store the resources specific to your application, such as descriptions of its 
menus, windows, controls, and dialog boxes, in the resource fork of your application. 
You can store resources specific to a document created by your application in the 
resource fork of the document file. 


The resource map in the resource fork of a file contains entries that provide the location 
of each resource in the resource fork. When the Resource Manager opens the resource 
fork of a file, it reads the resource map into memory. As the Resource Manager reads 
resources into memory, it replaces their entries in the resource map with handles to their 
data in memory. The Resource Manager always searches the resource map in memory, 
not the resource map of the resource fork on disk, when it searches for a resource. If a 
requested resource is in memory, the Resource Manager uses the resource in memory; 
otherwise it reads the resource from the resource fork on disk into memory. 


Once the Resource Manager has opened a resource fork and read its resource map into 
memory, it keeps the map in memory until the file is closed. You can specify that a 
resource be read into memory immediately when the Resource Manager opens a file’s 
resource fork, or you can specify that the Resource Manager read it into memory only 
when needed. The Resource Manager stores resources from resource forks opened by 
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your application in relocatable blocks in your application’s heap. You can also specify 
whether the Resource Manager should purge a resource from memory in order to make 
room in memory for other data. If you specify that a resource is purgeable, you need to 
use the Resource Manager to make sure the resource is in memory before accessing it 
through its resource handle. 


When a user opens your application, system software opens your application’s resource 
fork. When your application opens a file, your application typically opens both the 

file’s data fork and the file’s resource fork. When your application requests a resource 
from the Resource Manager, the Resource Manager follows a specific search order. 

(If necessary, your application can change the search order using Resource Manager 
routines.) The Resource Manager normally looks first for the resource in the resource 
fork of the last file that your application opened. So, if your application has a single file 
open, the Resource Manager looks first in that file’s resource fork. If the Resource 
Manager doesn’t find the resource there, it continues to search each resource fork open 
to your application in the reverse order that the files were opened. After looking in the 
resource forks of files your application has opened, the Resource Manager searches your 
application’s resource fork. If it doesn’t find the resource there, it searches the resource 
fork of the System file. 


This search path allows your application to use resources defined in the System file, to 
override resources defined in the System file, to share resources between files by using 
resources stored in your application’s resource fork, and to override your application- 
defined resources and use resources specific to a document. 


A Macintosh file always contains both a resource fork and a data fork, although one 

or both of those forks can be empty. Document files typically contain the document’s 
data in the data fork and any document-specific resources—such as preference settings, 
window location, and the document icon—in the resource fork. The resource fork 

of an application typically includes resources that describe the application’s menus, 
windows, controls, dialog boxes, and icons, as well as the code itself, which is also stored 
as a resource. 


Whether you store data in the data fork or the resource fork of a document file depends 
largely on whether you can structure that data in a useful manner as a resource. 

For example, it’s often convenient to store document-specific settings, such as the 
document’s previous window size and location, as a resource in the document’s resource 
fork. Data that is likely to be edited by the user is usually stored in the data fork of 

a document. 


A resource fork can contain at most 2700 resources. The Resource Manager uses a linear 
search when searching a resource fork’s resource types and resource IDs. In general, you 
should not create more than 500 resources of the same type in any one resource fork. 


Inside Macintosh: More Macintosh Toolbox describes resources and the use of the Resource 
Manager in more detail. For information on writing data to a file’s data fork, see Inside 
Macintosh: Files. 
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Help Balloons 


Your application can provide help balloons for elements such as menus, dialog boxes, or 
the content area of a window. The chapter “Help Manager” in Inside Macintosh: More 
Macintosh Toolbox describes how your application can provide help balloons. You can 
also create help balloons for some elements of your application’s interface—such as its 
menus—using the application BalloonWriter, which is available from APDA. 


Copy and Paste 


All Macintosh applications should support the copying of data from and pasting of data 
to the Clipboard. The chapter “Scrap Manager” in Inside Macintosh: More Macintosh 
Toolbox describes how to copy data from the Clipboard and paste data to the Clipboard 
by using the Scrap Manager. 
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In addition to the managers provided by the Macintosh Toolbox, you can also use other 
managers and system software routines. For example, you can use QuickDraw routines 
to draw the content of your application’s windows, TextEdit (in conjunction with the 
Dialog Manager) to handle editable text items in dialog boxes, the File Manager to read 
and write files, the Process Manager and Memory Manager to control various aspects of 
your application’s execution, and the Edition Manager and Apple Event Manager to 
support interapplication communication. The rest of this chapter describes some of these 
managers and where you can find more information about them. 


Drawing on the Screen 


System software routines, such as the routines provided by QuickDraw, perform all 
drawing on the screen. For example, your application tells QuickDraw what and where 
to draw, and QuickDraw does the actual drawing to the screen. The graphics routines 
provided by system software support quick drawing of objects such as circles, ovals, 
rectangles, lines, text, and pictures. See Inside Macintosh: Imaging for specific graphics- 
related information. 


Handling Text 


You can use the system software routines provided by TextEdit to greatly simplify basic 
text editing and formatting that your application would otherwise have to implement. 
For example, most applications use editable text items in dialog boxes; your application 
can use the Dialog Manager (which calls TextEdit) to automatically handle user 
interaction in editable text items. The Dialog Manager and your application can use 
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TextEdit to insert new text, delete characters that the user backspaces over, scroll text 
within a window, cut text, copy text, paste text, select text, and handle word wrapping. 
Most applications use TextEdit only for simple text editing in a dialog box and use their 
own techniques for handling editable text in document windows. 


You should design your application so that it can handle text in more than one language 
or script. System software provides many routines to help you accomplish this. For 
example, if your application automatically displays the date in the footer of your 
document, you can use Text Utility routines to automatically display the date in the 
format common to the current script. Similarly, if your application provides a Find 
command, it can use Text Utility routines to search according to the word-break tables 
and according to the current script. 


See Inside Macintosh: Text for information on how you can provide support for text 
editing in documents created by your application and for information on designing your 
application so that it can support text editing in more than one language or script. 


Managing Files 


When the user chooses the Save or Save As menu command, you usually write to a file 
the data that the user has entered in the active window. When the user selects a file 
using the Open command, you read information from a file. You can use the File 
Manager to read and write files. You can use the system software routines provided by 
the Standard File Package to present a standard and consistent interface to the user 
when saving and opening files. See the chapters “Introduction to File Management” and 
“Standard File Package” in Inside Macintosh: Files for information about these topics. 


Allocating Memory and Launching Processes 


For information about how the Process Manager launches your application, see 

the chapter “Process Manager” in Inside Macintosh: Processes. See the chapter 
“Introduction to Memory Management” in Inside Macintosh: Memory for informa- 

tion about how system software manages memory; how you can manage the memory 

in your application’s partition effectively; and how your application can allocate, release, 
or manipulate memory. 


Creating Publishers and Subscribers 


Your application should support Edition Manager features so that users can share and 
automatically update data between documents. See the chapter “Edition Manager” in 
Inside Macintosh: Interapplication Communication for information about supporting publish 
and subscribe features. 
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Communicating With Other Applications 


System software provides various means of communication between applications. You 
can use Event Manager routines to communicate, in the form of high-level events, with 
other applications. High-level events are not required to adhere to any specific protocol, 
so their interpretation is defined by each application that sends or receives them. Apple 
events are high-level events that follow a standard defined protocol (the Apple Event 
Interprocess Messaging Protocol). In most cases, you should use Apple events for 
communication between applications. Because Apple has defined a standard set of 
Apple events, all applications can interpret specific Apple events in the same way and 
respond in an expected manner. 


Both the Event Manager and Apple Event Manager rely on the services of the 
Program-to-Program Communications (PPC) Toolbox to actually send and receive 
events between applications. Your application can also directly access the PPC Toolbox if 
you need to get additional control or services not provided by the Event Manager or 
Apple Event Manager. 


If your application supports publish and subscribe features, the Edition Manager sends 
your application Apple events to notify it when new data is available for a subscriber or 
to request that it create a new publisher. 


For information on Apple events, publish and subscribe features, or direct access to the 
PPC Toolbox, see Inside Macintosh: Interapplication Communication. 


Designing Your Application 


1-16 


As previously described, you'll need to make extensive use of this book and Macintosh 
Human Interface Guidelines as you begin to design your application. Once you implement 
the basic elements of a Macintosh application, you can begin to add features unique to 
your application. Once again, you'll find Macintosh Human Interface Guidelines and other 
books in the Inside Macintosh library valuable tools as you create applications. 
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This chapter describes how your application can use the Toolbox Event Manager to 
receive information about actions performed by the user, to receive notice of changes in 
the processing status of your application, and to communicate with other applications. 


For example, you can retrieve information from the Toolbox Event Manager that gives 
your application details about whether the user has pressed a key or the mouse button, 
whether one of your application’s windows needs updating, or whether some other 
hardware-related or software-related action requires a response from your application. 


Your application also uses the Event Manager to support the cooperative, multitasking 
environment available on Macintosh computers. This environment allows users to 
switch between many open applications and allows other applications to receive 
background processing time. By using Event Manager routines, you allow the system 
software to coordinate the scheduling of processing time between your application and 
other applications. 


The Event Manager and Process Manager maintain the cooperative, multitasking 
environment. The Process Manager coordinates the scheduling of applications, and the 
Event Manager communicates information about changes in your application’s 
processing status to your application. 


See the chapter “Process Manager” in Inside Macintosh: Processes for complete 
information on how the Process Manager schedules applications for execution. 


You can use the Event Manager to communicate with other applications. Your 
application can also communicate with other applications using the services of the Apple 
Event Manager. 


The Event Manager and Apple Event Manager routines that let your application 
communicate with other applications depend on the services of the Program-to-Program 
Communications (PPC) Toolbox. The services performed by the Event Manager and 
Apple Event Manager meet the needs of most applications for interapplication 
communication. However, to get additional control or capabilities not provided by the 
Event Manager or Apple Event Manager, you can choose to access the PPC Toolbox 
directly. The chapter “Program-to-Program Communications Toolbox” in Inside 
Macintosh: Interapplication Communication describes the PPC Toolbox routines that are 
available to your application. 


For a comparison of the services provided by the Event Manager, Apple Event Manager, 
and PPC Toolbox, see Inside Macintosh: Interapplication Communication. For additional 
information about Apple events, including descriptions of how to process the required 
Apple events, see Inside Macintosh: Interapplication Communication. 


This chapter describes both the Toolbox Event Manager and the Operating System Event 
Manager. The Operating System Event Manager maintains a queue in which it stores 
hardware-related occurrences that you may want your application to respond to. The 
Toolbox Event Manager communicates the information maintained by the Operating 
System Event Manager to your application. In most cases, your application needs to 
interact only with the Toolbox Event Manager. In this chapter, the name Event Manager 
refers to the Toolbox Event Manager. 
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This chapter provides a general introduction to events and then explains how you can 
use the Event Manager to 


m receive keypresses and mouse clicks as input for your application 
m receive indication that your application’s windows need to be activated or updated 


m allow other applications to use the available system resources when your application 
isn’t using them 


™ communicate with other applications 


Introduction to Events 


Most Macintosh applications receive information about hardware and software 
occurrences that require a response from the application, through events. An event is the 
means by which the Event Manager communicates information about user actions, 
changes in the processing status of the application, and other occurrences that require a 
response from the application. 


The Event Manager communicates information about events that occur through the 
event record. The Event Record data type defines the event record. The event record 
contains information about what type of event occurred (a mouse click or keypress, for 
example) and contains additional information associated with the event (for example, for 
a keypress the Event Manager also reports which key was pressed). 


Most Macintosh applications are event-driven—that is, they respond to various changes 
or occurrences and take action based on the nature of the event. Typically, a Macintosh 
application repeatedly checks to see if an event has occurred and, if so, responds to the 
event. If no events are pending, the application can choose to relinquish the processor for 
a specified amount of time or can perform other tasks before checking again to see 
whether an event has occurred. 


Your application typically retrieves events from the Event Manager and also relinquishes 
processor time by using the WaitNextEvent function. If any events are pending for 
your application, the WaitNextEvent function returns the event to your application. If 
no events are pending for your application, the WaitNextEvent function may allocate 
processing time to other applications. 








When multiple applications are open, the user chooses one to interact with at any given 
time. The active application (or foreground process) is the one currently interacting with 
the user. The foreground process displays its menu bar, and its windows are in front of 
the windows of all other applications. (The term process refers to an open application or, 
in some cases, an open desk accessory.) 


There can be only one foreground process at any one time; however, multiple processes 
can exist in the background. A background process is a process that is not currently 
interacting with the user. The foreground process has first priority for accessing the 
CPU. Other processes can access the CPU only when the foreground process yields time 
to them. 
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By using WaitNextEvent to retrieve events, you allow other applications to make use 
of processing time that your application would otherwise not use. When your 
application is in the background, it in turn can receive processing time when other 
applications relinquish the CPU. Using WaitNextEvent also allows users to switch 
between multiple open applications. 





An application that is in the background can get CPU time but can’t interact with the 
user while it is in the background. (However, the user can choose to bring the 

application to the foreground—for example, by clicking in one of the application’s 
windows.) An application can also post a notification request using the Notification 
Manager if the application is in the background and requires the user’s attention. Any 
application that has the canBackground flag set in its size (' SIZE") resource is eligible 
to obtain access to the CPU when it is in the background. 





At any given time a process is either in the foreground or the background; a process can 
switch between the two states at well-defined times. 


The Event Manager ensures that switching between applications occurs in a smooth 
fashion—by sending your application an event when it is about to be suspended and 
sending it an event when it has processing time again and can resume executing. The 
Event Manager and Process Manager coordinate this switching and scheduling of 
processor time among many applications. 


Your application can receive various types of events: low-level events, operating-system 
events, and high-level events. 


The Event Manager returns low-level events to your application for occurrences such as 
the user pressing the mouse button, releasing the mouse button, pressing a key on the 
keyboard, or inserting a disk. The Event Manager also returns low-level events to your 
application if your application needs to activate (make changes to a window based on 
whether it is in front or not) or update (redraw the contents of) one of its windows. 
When your application requests an event and there are no other events to report, the 
Event Manager returns a null event. 


The Event Manager returns operating-system events to your application when the 
processing status of your application is about to change or has changed. For example, if 
a user brings your application to the foreground, the Process Manager sends an event 
through the Event Manager to your application. Some of the work of reactivating your 
application is done automatically, both by the Process Manager and by the Window 
Manager; your application must take care of any further processing needed as a result of 
your application being reactivated. 


The Event Manager returns high-level events to your application as a result of 
communication directed to your application from another application or process. 


Low-level events, except for update events and null events, are always directed to the 
foreground process. Operating-system events are also always directed to the foreground 
process. High-level events, update events, and null events can be directed to the 
foreground process or background processes. 
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You can specify which types of events you want your application to receive. You do this 
by specifying an event mask as a parameter to various Event Manager routines. An 
event mask allows you to mask out the events you are not interested in receiving. For 
example, you can accept all events except high-level events. 


Events can originate from a number of different sources: the Operating System Event 
Manager, Window Manager, Process Manager, and PPC Toolbox. Figure 2-1 shows the 
relationships between the Toolbox Event Manager, other parts of the system software, 
and your application. 


Figure 2-1 Sources of events sent to your application 
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The Operating System Event Manager creates and maintains a queue referred to as the 
Operating System event queue. The Operating System Event Manager detects and 
reports low-level hardware-related events such as mouse clicks, keypresses, and disk 
insertions. The Operating System Event Manager places these events in the Operating 
System event queue. The Toolbox Event Manager retrieves events from this event queue 
and returns events, one at a time at your application’s request, to your application. 
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A maximum of 20 events can be pending in the Operating System event queue. If the 
Operating System event queue becomes full, the Operating System Event Manager 
begins to discard old events to make room for new ones as events are posted. The 
Operating System Event Manager always discards the oldest event in the queue when 
it must discard an event. However, this is not a common occurrence; your application 
typically processes events much faster than the user can generate them. The actual 
capacity of the event queue is determined by system startup information stored on 

the startup volume; see the chapter “File Manager” in Inside Macintosh: Files for system 
startup information. 


The Event Manager can also report events from the Window Manager and Process 
Manager. If a window needs to be updated, activated, or deactivated, the 

Window Manager directs an event to the Toolbox Event Manager. Similarly, the 
Process Manager directs an event to the Toolbox Event Manager if the processing 
status of your application changes. The Toolbox Event Manager reports these events 
to your application. 


Note 

On computers running System 6, MultiFinder provides some of 
the capabilities supplied by the Process Manager in System 7. On 
computers running System 6 without MultiFinder, only a single- 
application environment is supported. @ 


Your application can use the Event Manager to send and receive high-level events. To 
transmit high-level events between applications, the Event Manager uses the PPC 
Toolbox on behalf of your application. For each open application capable of receiving 
high-level events, the Event Manager maintains a separate queue, referred to as the 
application’s high-level event queue, to store high-level events. The size of an 
application’s high-level event queue is limited only by the amount of available memory. 


Your application’s event stream consists of those events that are available to your 
application for retrieval when it makes a request for an event. For example, when your 
application is in the background, its event stream can contain only update events, null 
events, and high-level events. 


When your application asks the Event Manager for the next event, the Event Manager 
returns the next available event according to its priority. In general, the Event Manager 
returns events in this order of priority: 


1. low-level events 
2. operating-system events 
3. high-level events 


The next sections describe low-level events, operating-system events, and high-level 
events in greater detail. 
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Low-Level Events 


The Event Manager uses low-level events to report very low-level hardware and 
software occurrences. Low-level events report 


m actions by the user (such as pressing the mouse button, typing on the keyboard, or 
inserting a disk) 


m changes in windows on the screen 
m that the Event Manager has no other events to report 


Low-level events that report actions by the user include mouse-down, mouse-up, 
key-down, key-up, auto-key, and disk-inserted events. The Event Manager reports any 
of these events when the user performs the action associated with each event. 


Mouse-down and mouse-up events report that the user pressed or released the mouse 
button. For these events the Event Manager returns the location of the cursor at the time 
the mouse button was pressed or released. Key-down and key-up events report that the 
user pressed or released a key. Auto-key events report that the user has held a key down 
for a certain amount of time. For keyboard-related events, the Event Manager reports 
which key was pressed. For mouse-related and keyboard-related events, the Event 
Manager also reports the state of the modifier keys (the Option, Command, Caps Lock, 
Control, and Shift keys) at the time of the event. 


When the user inserts a disk, the Operating System attempts to mount the volume on the 
disk by calling the File Manager function PBMount Vol. The Operating System Event 
Manager then generates a disk-inserted event. If the user is interacting with a standard 
file dialog box, the Standard File Package intercepts the disk-inserted event and handles 
it. Otherwise, the event is left in the event queue for your application to retrieve. In most 
cases your application can handle unexpected disk-inserted events by simply checking 
to see if the volume was successfully mounted. 


Update events and activate events are two types of low-level events that the Event 
Manager can report as a result of changes in the appearance of windows on the screen. 
For example, if a user is working with several open documents belonging to your 
application, you can allow the user to switch from one document to another when the 
user clicks in the appropriate window. You can determine whether the user clicked in 
another window by using the Window Manager function FindWindow,; if the user 
clicked in another window, you can then use the Window Manager procedure 
SelectWindow to generate the necessary activate events. Before the Event Manager 
sends your application any activate events relating to this occurrence, the Window 
Manager does some work for you, such as unhighlighting the deactivated window and 
highlighting the newly activated window. At your application’s next request for an 
event, the Event Manager returns an activate event. 


An activate event indicates the window involved and whether the window is becoming 
activated or deactivated. Your application should perform any other necessary actions to 
complete the transformation of the window from active to inactive or vice versa. For 
example, when a window becomes active, your application should show any scroll bars 
and restore any selections. 
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Your application typically receives an activate event for the window being deactivated, 
followed by an activate event for the window becoming active at your application’s next 
request for an event. 


Note 

If the user switches between your application and another application 
(by clicking in the window of another application, for example), your 
application is responsible for activating or deactivating any windows 
as appropriate. Your application is notified of this occurrence 

through operating-system events. If your application has the 

accept SuspendResumeEvents and doesActivateOnFGSwitch 
flags set in its 'SIZE' resource, your application is notified of the 
switch through an operating-system event and does not receive a 
separate activate event when the user switches between applications. 








The Window Manager generates update events to control the appearance of windows on 
the screen. The Window Manager keeps track of the front-to-back ordering of windows 
and allows windows to overlap other windows. The Window Manager coordinates the 
display of windows. When one window covers another window and then the user 
moves the first window, the Window Manager generates an update event so that the 
contents of the newly exposed area can be updated. The Event Manager reports update 
events as needed to the applications whose windows need updating. Unlike other 
low-level events, update events can be directed to the foreground process or background 
processes. 


Activate and update events generated by the Window Manager are not placed into the 
Operating System event queue but are sent directly to the Event Manager. 


The Event Manager reports a null event when your application requests an event and 
your application’s event stream does not contain any of the requested event types. By 
using the WaitNextEvent function, you can yield time to other processes when null 
events are the only pending events for your application. 


When your application receives a null event, your application can do idle processing 
(such as blinking the caret) if it is in the foreground or do other tasks if it is in the 
background. If you want your application to receive null events when it is in the 
background, you must set the canBackground flag in your application’s 'SIZE' 
resource. If your application does not perform any processing in response to null events 
when it is in the background, then set the cannotBackground flag. If you set the 
cannotBackground flag, the Event Manager does not report null events to your 
application when it is in the background. However, the Event Manager still reports 
update events (and high-level events if the isHighLevelEventAware flag is set in the 
'SIZE' resource) to your application when it is in the background regardless of how the 
background flag is set. 





Figure 2-2 shows the various kinds of low-level events your application can receive. See 
“Handling Low-Level Events” beginning on page 2-32 for complete details of how your 
application should respond to low-level events. 
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Figure 2-2 Low-level events 
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Operating-System Events 


The cooperative, multitasking environment allows the user to interact with your 
application and with other applications. The Process Manager coordinates the 
scheduling of applications, and the Event Manager communicates information about 
changes in the operating status of applications to the applications involved. 


For example, when your application is about to be switched into the background, the 
Event Manager sends it a suspend event. Then, when your application is switched back 
into the foreground, it receives a resume event. These types of events, as well as a special 
type of mouse event, the mouse-moved event, are known as operating-system events. 


Figure 2-3 illustrates how the Event Manager helps provide this cooperative, 
multitasking environment. The Process Manager generates suspend, resume, and 
mouse-moved events, and the Event Manager reports these events to applications. 
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Figure 2-3 Operating-system events 
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Note 

If your application sets the accept SuspendResumeEvents and 
doesActivateOnFGSwitcnh flags inits 'SIZE' resource, your 
application is also responsible for activating or deactivating any 
windows as appropriate in response to operating-system events. For 
maximum compatibility, your application should set these flags and 
handle suspend and resume events. See “The Size Resource” beginning 
on page 2-115 for more information on these and other flags in the 
'SIZE' resource. @ 











When your application receives a suspend event, it does not actually switch to the 
background until it makes its next request to receive events from the Event Manager. At 
the time that it receives the suspend event, your application should convert any private 
scrap into the global scrap if necessary. Your application should hide scroll bars, remove 
the highlighting from any selections, and hide any floating windows. If your application 


Introduction to Events 2-11 


2-12 


CHAPTER 2 


Event Manager 


shows a window that displays the Clipboard contents, you should hide this window 
also. Then you should call WaitNextEvent to relinquish the CPU and allow the 
Operating System to schedule other processes for execution. It is important to minimize 
the processing you do in response to a suspend event so that the computer appears 
responsive to the user. 





When control returns to your application, the first event it receives is a resume event. 
Your application should convert the global scrap back to its private scrap, if necessary. 
Your application should also restore any windows to the state the user left them in at the 
time of the previous suspend event. For example, your application should show any 
scroll bars, highlight any selections, and show any floating windows. See “Responding 
to Suspend and Resume Events” beginning on page 2-60 for complete details of how 
your application should respond to these events. 


The events that your application can receive in the background are update, null, and 
high-level events. When your application is in the background, it should not perform 
any processing that would make the foreground process appear unresponsive to the 
user. When receiving events in the background, your application should perform any 
needed action in response to an event and then quickly return. 


Your application should never interact with the user when it is in the background. If you 
need to notify the user of some special occurrence while your application is executing 

in the background, you should use the Notification Manager to queue a notification 
request. You should not attempt to display an alert box while your application is in the 
background. Instead, your application can specify that the Notification Manager play 

a sound, display an alert box, cause a small icon representing your application to 

blink in alternation with the Application menu icon, display a diamond next to your 
application’s name in the Application menu, or put a combination of these actions 

into effect. 


These actions are designed to alert the user that another application needs the user’s 
attention. By using the Notification Manager you help maintain the user interface 
principle of giving the user control, as the user can choose to bring the application 
requesting attention to the foreground at the user’s convenience. See the chapter 
“Notification Manager” in Inside Macintosh: Processes for examples of how to post 
notification requests. 


Another kind of operating-system event is the mouse-moved event. You can request that 
the Event Manager send your application a mouse-moved event whenever the cursor 

is outside of a region that you specify to the WaitNextEvent function. For example, 
you can use mouse-moved events as a convenient way for your application to change 
the appearance of the cursor as the user moves the cursor from the text area of a 
document to the scroll bar. See “Responding to Mouse-Moved Events” beginning on 
page 2-62 for detailed examples. 
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High-Level Events 


The Event Manager provides routines that let applications communicate with each other 
by exchanging high-level events. A high-level event is an event that your application 
can send to another application to give it some information, to receive some information 
from it, or to have it perform some action. 


For example, your application can send a high-level event to another application 
instructing that application to perform a specific action, such as adding a row toa 
spreadsheet or changing the font size of a paragraph. Your application can also send a 
high-level event to another application requesting information from that application— 
for example, requesting a dictionary application to return the definition of a particular 
word. When you send a high-level event to another application, you can also include 
additional information or commands in an optional data buffer. For example, your 
application can use a high-level event to send a list of new words and definitions to a 
dictionary application. 


Note 


High-level events are available only in system software 
version 7.0 or later. @ 


Figure 2-4 on the next page shows three different applications communicating with each 
other by sending and receiving high-level events. The Event Manager uses the PPC 
Toolbox to transmit high-level events. The Event Manager maintains a high-level event 
queue for each application that has identified itself as capable of receiving high-level 
events. The high-level event queues are limited in size only by available memory. 


For effective communication between applications, your application must define the set 
of high-level events it responds to and let other applications know the events it accepts. 
By implementing the capabilities to send events to and receive events from other 
applications, you allow other applications to interact with your application and provide 
enhanced capabilities to your users. 


Generally, there is no restriction on the type of processing that one application can 
request from another by sending it a high-level event. For a high-level event sent by one 
application to be understood by another application, however, the sender and receiver 
must agree on a protocol, that is, on the way the event is to be interpreted. Apple events 
are high-level events whose structure and interpretation are determined by the Apple 
Event Interprocess Messaging Protocol (AEIMP). 


Your application should support the required Apple events, as described in Inside 
Macintosh: Interapplication Communication. The Finder uses the required Apple events to 
provide your application with information when it is opened and to give it the names of 
documents to open or print when the user opens or prints documents from the Finder. 
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Figure 2-4 High-level events 
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In addition, you may want your application to support other common Apple events. 
For example, the Edition Manager uses Apple events to communicate information 
about document sections among the various applications that may publish sections 
or subscribe to them. The Edition Manager sends the appropriate Apple events 

to applications that want to maintain up-to-date subscriber sections within their 
documents. If a user alters a section of a document that has previously been published 
and updates the edition, the Edition Manager might post an Apple event to the 
application indicating that a new edition is available. The application receiving the 
Apple event can then update the subscriber or ignore the information, as the user 
dictates. For complete information on responding to Apple events sent by the Edition 
Manager, see the chapter “Edition Manager” in Inside Macintosh: Interapplication 
Communication. 
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To ensure compatibility and smooth interaction with other Macintosh applications, 
you should use the Apple event protocol for high-level events whenever possible. 
You should define new protocols only if your application must communicate with 
applications on other computers that use different protocols or if your application 
has other special needs. For complete information about Apple events and about 
implementing the required set of Apple events, see Inside Macintosh: Interapplication 
Communication. 


Note 
All Macintosh system software that sends or receives high-level events 
uses the Apple events protocol. 


Priority of Events 

Each type of event has a certain priority. The Event Manager returns events in this order 
of priority: 

1. activate events 


2. mouse-down, mouse-up, key-down, key-up, and disk-inserted events in FIFO 
(first-in, first-out) order 


auto-key events 


update events (in front-to-back order of windows) 


3. 
4. 
5. operating-system events (suspend, resume, mouse-moved) 
6. high-level events 

is 


null events 


Several of the Event Manager routines can be restricted to operate on one or more 
specific types of events. You do this by disabling (or “masking out”) the events you are 
not interested in receiving. See “Setting the Event Mask” beginning on page 2-26 for 
details about specifying the types of events you wish to receive. 


Switching Contexts 


Processes running in the background receive processing time when the foreground 
process makes an event call (that is, calls WaitNextEvent or EventAvail) and there 
are no events pending for that foreground process. A process running in the background 
should relinquish the CPU regularly to ensure a timely return to the foreground process 
when necessary. 








In System 7 (or with MultiFinder in earlier versions), the available processing time is 
distributed among multiple processes through a procedure known as context switching 
(or just switching). All switching occurs at a well-defined time, namely, when an 
application calls WaitNextEvent. When a context switch occurs, the Process Manager 
allocates processing time to a process other than the one that had been receiving 
processing time. Two types of context switching may occur: major and minor. 
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A major switch is a complete context switch: an application’s windows are moved from 
the back to the front, or vice versa. In a major switch, two applications are involved, the 
one being switched to the foreground and the one being switched to the background. 
The Process Manager switches the A5 worlds of both applications, as well as the relevant 
low-memory environments. If those applications receive suspend and resume events, 
they are so notified at the time that a major switch occurs. 


A minor switch occurs when the Process Manager gives time to a background process 
without bringing the background process to the front. The two processes involved in a 
minor switch can be two background processes or a foreground process and a 
background process. As in a major switch, the Process Manager switches the A5 worlds 
and the low-memory environments of the two processes. However, the order of 
windows is not switched, and neither process receives either suspend or resume events. 


When the frontmost window is an alert box or a modal dialog box, major switching does 
not occur, although minor switching can. To determine whether major switching can 
occur, the Operating System checks (among other things) to see if the window definition 
procedure of the frontmost window is dBoxP roc, because the type dBoxProc is 
specifically reserved for alert boxes and modal dialog boxes. (If the frontmost window is 
a movable modal dialog box, major switching can still occur.) 


Note 

Your application can also get switched out if it calls a system software 
routine that makes an event call. For example, when your application 
calls ModalDialog, a minor switch can occur. 


Your application can receive processing time and perform tasks in the background, 
but your application should not interact with the user or perform tasks that would slow 
down the responsiveness of the foreground process. 


Your application indicates scheduling options to the Operating System, such as whether 
the application can use null-event processing time when in the background, whether it 
can accept suspend and resume events, and so forth, by setting flags in its size ('SIZE') 
resource. Every application executing in System 7, as well as every application executing 
in System 6 with MultiFinder, should contain a 'SIZE' resource. See “Creating a Size 
Resource” beginning on page 2-30 for details on how to specify this information. 
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actions performed by the user and give notice of changes in the processing status of your 
application. The Event Manager also provides routines that your application can use to 
communicate with other applications. You can control the scheduling of your application 
for execution by using the Event Manager. 
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The rest of this chapter explains 


m how to structure your main event loop to receive and process events 





m how to create a 'SIZE' resource to specify your application’s memory requirements 
and scheduling options 


m how to respond to most types of events 
m how to receive and process high-level events 


m how to send high-level events to other applications 


Using the Event Manager 


You can use the Event Manager to receive information about hardware-related events, 
about changes in the appearance of your application’s windows, or about changes in 
the operating status of your application. You can also use the Event Manager to 
communicate directly with other applications. This communication can include sending 
events to other applications, receiving events from other applications, and searching for 
specific events from other applications. 


Your application can both send and receive high-level events, but it generally only 
receives low-level events and should not send them. Your application receives low-level 
events, operating-system events, and high-level events in the same way, which is by 
asking the Event Manager for the next available event. If the event your application 
receives is a high-level event, your application might need to use another Event Manager 
or Apple Event Manager routine to retrieve an optional data buffer and additional 
information accompanying that event. 


Before using the Event Manager, you can use the Gestalt function to determine if 
certain features of the Event Manager are available. See the chapter “Gestalt Manager” in 
Inside Macintosh: Operating System Utilities for information on the Gestalt function. 


If your application sends or receives high-level events, you should use the Gestalt 
function with the gestaltPPCToolboxAttr selector to determine whether the PPC 
Toolbox is present. Use the Gestalt function with the gestaltOSAttr selector to see 
if the Process Manager is available. If the PPC Toolbox and the Process Manager are 
present, then the system software provides support for high-level events. 


If your application sends or receives Apple events, use the Gestalt function with the 
gestaltAppleEventsAttr selector to determine whether the Apple Event Manager 
is available. 


Your application needs to initialize QuickDraw, the Font Manager, and the Window 
Manager before using the Event Manager. Your application can accomplish this 
initialization by using the InitGraf, InitFonts, and InitWindows procedures. 
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When your application starts, you can call the FlushEvents procedure to empty 
the Operating System event queue of any low-level events left unprocessed by 
another application. For example, you might want to remove any mouse-down 

events or keyboard events that the user might have entered while the Finder launched 
your application. 


This section shows how to retrieve events from the Event Manager, how to mask out 
unwanted events, how to specify memory and scheduling options for your application, 
and how to handle each type of event received from the Event Manager. 


Obtaining Information About Events 


You get information about events through the event record. The Event Record data 
type defines the event record and has this structure: 


TYPE EventRecord = 





RECORD 
what: Integer; {event code} 
message: LongInt; {event message} 
when: LongInt; {ticks since startup} 
where: Point; {mouse location} 
modifiers: Integer; {modifier flags} 

END; 


Field descriptions 


what The what field indicates the type of event received. The type of 
event can be identified by these constants: 

















CONST 
nullEvent = 0; {no other pending events} 
mouseDown = 1; {mouse button pressed} 
mouseUp = 2; {mouse button released} 
keyDown = 3; {key pressed} 
keyUp = 4; {key released} 
autoKey = 5; {key repeatedly held down} 
updateEvt = 6; {window needs updating} 
diskEvt = 7; {disk inserted} 
activateEvt = 8; {activate/deactivate window} 
osEvt = 15; {operating-system event-—- } 
{ resume, suspend, or } 
{ mouse-moved} 
kHighLevelEvent = 23; {high-level event} 
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message 


when 


where 


The message field contains additional information associated with 
the event. The interpretation of this information depends on the 
event type. The contents of the message field for each event type 
are summarized here: 


Event type 


null, mouse-up, 
mouse-down 


key-up, 
key-down, 
auto-key 


update, activate 
disk-inserted 


resume 


suspend 


mouse-moved 


high-level 


Event message 
Undefined. 


Character code and virtual key code in 
low-order word. For Apple Desktop Bus 
(ADB) keyboards, the low byte of the 
high-order word contains the ADB address 
of the keyboard where the keyboard event 
occurred. The high byte of the high-order 
word is reserved. 


Pointer to the window to update, activate, or 
deactivate. 


Drive number in low-order word, File 
Manager result code in high-order word. 


The suspendResumeMessage constant in 
bits 24-31 and a 1 in bit 0 to indicate the 
event is a resume event. Bit 1 contains either 
a1 or a0 to indicate if Clipboard conversion 
is required, and bits 2-23 are reserved. 


The suspendResumeMessage constant in 
bits 24-31 and a 0 in bit 0 to indicate the 
event is a suspend event. Bit 1 is undefined, 
and bits 2-23 are reserved. 


The mouseMovedMessage constant in bits 
24-31. Bits 2-23 are reserved, and bit 0 and 
bit 1 are undefined. 





Class of events to which the high-level event 
belongs. The message and where fields of 

a high-level event define the specific type of 
high-level event received. 


The when field indicates the time when the event was posted (in 
ticks since system startup). When needed, you can use the when 
field to compare how much time has elapsed between successive 


mouse events. 


For low-level events and operating-system events, the where field 
contains the location of the cursor at the time the event was posted 
(in global coordinates). 


For high-level events, the where field contains a second event 
specifier, the event ID. The event ID defines the particular type of 
event within the class of events defined by the message field of the 
high-level event. For high-level events, you should interpret the 
where field as having the data type OSType, not Point. 
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modifiers The modifiers field contains information about the state of the 
modifier keys and the mouse button at the time the event was 
posted. For activate events, this field also indicates whether the 
window should be activated or deactivated. In System 7 it also 
indicates whether a mouse-down event caused your application to 
switch to the foreground. 


Each of the modifier keys is represented by a specific bit in the modifiers field of the 
event record. Figure 2-5 shows how to interpret the modifiers field. You can examine 
the modifiers field of the event record to determine which, if any, of the modifier keys 
were pressed at the time of the event. The modifier keys include the Option, Command, 
Caps Lock, Control, and Shift keys. If your application attaches special meaning to any 
of these keys in combination with other keys or when the mouse button is down, you 
can test the state of the modifiers field to determine the action your application should 
take. For example, you can use this information to determine whether the user pressed 
the Command key and another key at the same time to make a menu selection. 


Figure 2-5 The modifiers field of the event record 
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Bit 0 in the modifiers field gives additional information that is valid only if the event is 
an activate event or a mouse-down event. 


For activate events, the value of bit 0 is 1 if the window pointed to by the event message 
should be activated, and the value is 0 if the window should be deactivated. 


For mouse-down events in System 7, bit 0 indicates whether a mouse-down event 
caused your application to switch to the foreground. If so, bit 0 contains 1; otherwise, 
it contains 0. 
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You can also use these constants as masks to test the setting of various bits in the 
modifiers field: 


CONST activeFlag 


13 {set if window being activated or if } 
{ mouse-down event caused fgnd switch} 


btnState = 128; {set if mouse button up} 
cmdKey = 256; {set if Command key down} 
shiftKey = 512; {set if Shift key down} 
alphaLock = 1024; {set if Caps Lock key down} 
optionkey = 2048; {set if Option key down} 
controlKey = 4096; {set if Control key down} 


Note that the bit giving information about the mouse button is set if the mouse button is 
up. The bits for the modifier keys are set if the corresponding key is down. 


Some keyboards do not distinguish between the right or left Control, Shift, and Option 
keys; for example, the virtual key code for the right Shift key and left Shift key might be 
the same. For these keyboards, if the user presses the Control, Shift, or Option key, the 
Event Manager sets only the bits corresponding to the shiftKey, optionKey, and 
controlKey constants. For keyboards that do distinguish between these keys, the 
Event Manager sets the bits in the modifiers field to indicate whether the right or left 
Control, Shift, or Option keys were pressed. For example, the Event Manager sets bit 13 
inthe modifiers field if the user presses the right Shift key and sets bit 9 if the user 
presses the left Shift key. In most cases your application should not need to distinguish 
between the left and right Control, Shift, and Option keys. 


Processing Events 


Applications receive events one at a time by asking the Event Manager for the next 
available event. You use Event Manager routines to receive (or in the case of 
EventAvail, simply to look at) the next available event that is pending for your 
application. You supply an event record as a parameter to the Event Manager routines 
that retrieve events. The Event Manager fills out the event record with the relevant 
information about that event and returns it to your application. 





Your application can use the WaitNextEvent function to retrieve events from the Event 
Manager. If no events are pending for your application, the WaitNextEvent function 
may allocate processing time to other applications. If an event is pending for your 
application, the WaitNextEvent function returns the next available event of a specified 
type and removes the returned event from your application’s event stream. 





The EventAvail function gets the next available event of a specified type and returns it 
to your application, but does not remove the event from your application’s event stream. 
EventAvail thus allows your application to look at an event in the event stream 
without actually processing the event. 
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Note 

You can also use the GetNextEvent function to retrieve and remove an 
event; however, you should use WaitNextEvent to provide greater 
support for multitasking. # 








Using the WaitNextEvent Function 





Your application typically calls WaitNextEvent repeatedly. The next section, “Writing 
an Event Loop,” shows how to use WaitNextEvent with other routines to process 
events. This discussion focuses on the WaitNextEvent function itself. 








The WaitNextEvent function requires four parameters: 
m an event mask (eventMask) 

m anevent record (theEvent) 

m asleep value (sleep) 


m™ amouse region (nouseRgn) 





When WaitNextEvent returns, the event record contains information about the 
retrieved event, if any. 


The eventMask parameter specifies the events you are interested in receiving. 
WaitNextEvent returns events one at a time, in order of priority and at your 
application’s request, according to the value you specify in the eventMask parameter. If 
your application specifies that it doesn’t want to receive particular types of events, those 
events are not returned to your application when it makes a request for an event. 
However, those events are not removed from the event stream. (To remove events from 
the Operating System event queue, you can use the FlushEvents procedure with a 
mask specifying only those events you wish to remove from the queue.) See “Setting the 
Event Mask” beginning on page 2-26 for examples of how to use constants to set the 
value of the eventMask parameter. 





The sleep parameter specifies the amount of time (in ticks) for which your application 
agrees to relinquish the processor if no events are pending for it. When that time expires 
or when an event becomes available for your application, the Process Manager schedules 
your application for execution. In general, you should specify a value greater than 0 in 
the sleep parameter so that other applications can receive processing time if they need 
it. If the user is editing text and your application needs to blink the caret at periodic 
intervals or uses TextEdit to blink the caret, your application should not specify a value 
greater than the value returned by the Get Caret Time function. 


In the mouseRgn parameter you specify a screen region inside of which the Event 
Manager does not generate mouse-moved events. You should specify the region in 
global coordinates. If the user moves the cursor outside of this region and your 
application is the foreground process, the Event Manager reports mouse-moved events. 
Your application should recalculate the mouseRgn parameter when it receives a 
mouse-moved event; otherwise it will continue to receive mouse-moved events as long 
as the cursor is outside of the original region. If you pass an empty region or aNIL 
region handle, the Event Manager does not return mouse-moved events. You can use the 
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mouseRgn parameter as a convenient way to change the shape of the cursor—for 
example, when the user moves the cursor from the content area of a window to the scroll 
bar. See “Responding to Mouse-Moved Events” beginning on page 2-62 for information 
on how to set and change the mouseRgn parameter. 


Listing 2-1 shows an example of using the WaitNextEvent function. 








Listing 2-1 Using the WaitNextEvent function 
VAR 
eventMask: Integer; 
event: EventRecord; 
cursorRgn: RgnHandle; 
mySleep: LongInt; 
gotEvent: Boolean; 
eventMask := everyEvent; {accept all events} 
mySleep := MyGetSleep; {set an appropriate sleep value} 
cursorRgn := MyGetRgn; {set the region as appropriate} 
gotEvent := WaitNextEvent (eventMask,event,mySleep, cursorRgn) ; 


The code in Listing 2-1 specifies that WaitNextEvent should return the next pending 
event of any kind, give up the processor if no events are pending, and return a 
mouse-moved event if the user moves the cursor out of the specified region. 





The WaitNextEvent function returns after retrieving an event or after the time 
specified in the sleep parameter has expired. If there are no events of the types 
specified by the eventMask parameter (other than null events) pending for your 
application, and the time specified in the sleep parameter has not expired, 
WaitNextEvent may allocate processing time to background processes. Once an 
event for your application occurs or the time specified in the sleep parameter 
expires, your application receives processing time again. 








WaitNextEvent returns a function result of TRUE if it has retrieved any event other 
than a null event. If there are no events of the types specified by the eventMask 
parameter (other than null events) pending for the application, WaitNextEvent 
returns FALSE. 


Before returning an event to your application, WaitNextEvent performs other 
processing and may intercept the event. The WaitNextEvent function: 








m Calls the Operating System Event Manager function SystemEvent to determine 
whether the event should be handled by your application or the Operating System. 
For example, if the event is a Command-Shift-number key sequence, the Event 
Manager intercepts the event and calls the corresponding 'FKEY' resource to perform 
the associated action. 


mu Makes the alarm go off if the alarm is set and the current time is the alarm time. The 
user sets the alarm using the Alarm Clock desk accessory. 
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mw Calls the SystemTask procedure, which gives time to each open desk accessory or 
device driver to perform any periodic action defined for it. A desk accessory or device 
driver specifies how often the periodic action should occur, and SystemTask gives 
time to the desk accessory or device driver at the appropriate interval. 


In System 7, the WaitNextEvent function reports a suspend event to your 
application when 


m your application is in the foreground and the user opens a desk accessory or other 
item from the Apple menu, 


m the user clicks in the window belonging to a desk accessory or another application, or 
m the user chooses another process from the Application menu. 


After your application is switched out, the Event Manager directs events (other than 
events your application can receive in the background) to the newly activated process 
until the user switches back to your application or another application. 


Writing an Event Loop 


In applications that are event-driven (that is, applications that decide what to do at any 
time by receiving and responding to events), you can obtain information about pending 
events by calling Event Manager routines. Since you call these routines repeatedly, the 
section of code in which you request events from the Event Manager usually takes the 
form of a loop; this section of code is called the event loop. 


Listing 2-2 shows a simple event loop (an application-defined procedure called 
MyEvent Loop) for an application running in System 7. 


Listing 2-2 An event loop 


PROCEDURE MyEventLoop; 



































VAR 
cursorRgn: RgnHandle; 
gotEvent: Boolean; 
event: EventRecord; 
BEGIN 
cursorRgn := NewRgn; {pass an empty region the first time thru} 
REPEAT 
gotEvent := WaitNextEvent (everyEvent, event, MyGetSleep, 
cursorkgn) ; 
IF (event.what <> kHighLevelEvent) AND (NOT gInBackground) 
THEN MyAdjustCursor(event.where, cursorRgn) ; 
IF gotEvent THEN {the event isn’t a null event, } 
DoEvent (event) { so handle it} 
ELSE {no event (other than null) to handle } 
DoIdle(event); { right now, so do idle processing} 
UNTIL gDone; {loop until user quits} 
END; 
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The MyEvent Loop procedure repeatedly uses WaitNextEvent to retrieve events. The 
WaitNextEvent function returns a Boolean value of FALSE if there are no events of the 
specified types other than null events pending for the application. WaitNextEvent 
returns TRUE if it has retrieved any event other than a null event. 




















After WaitNextEvent returns, the MyEvent Loop procedure first calls an application- 
defined routine, MyAdjustCursor, to adjust the cursor as necessary. You usually adjust 
the cursor in response to mouse-moved events, and often in response to other events as 
well. This code adjusts the cursor once every time through the event loop, when the 
application receives any event other than a high-level event. The code does not adjust 
the cursor if the event is a high-level event, because the where field of a high-level event 
contains the event ID, not the location of the cursor. The code also does not adjust the 
cursor if this application is in the background, as the foreground process is responsible 
for setting the appearance of the cursor. 


If WaitNextEvent retrieved any event other than a null event, the event loop calls 
DoEvent, an application-defined procedure, to process the event. Otherwise, the 
procedure calls an application-defined idling procedure, DoIdle. 


Note 

If your application uses modeless dialog boxes, you need to 
appropriately handle events in them. You can choose to handle events 
for modeless dialog boxes using the same routines that you use to 
handle events in other windows; this is the approach used throughout 
this chapter. Alternatively, you can choose to call the IsDialogEvent 
function in your event loop. See “Handling Events in a Dialog Box” on 
page 2-29 for information on handling events in alert boxes, modal 
dialog boxes, movable modal dialog boxes, and modeless dialog boxes. 
For additional information on dialog boxes, see the chapter “Dialog 
Manager” in this book. # 





If you intend to design your application to run in either a single-application environ- 
ment (such as System 6 without MultiFinder) or a multiple-application environment, 
the very beginning of your event loop should test to make sure the WaitNextEvent 
function is available. If WaitNextEvent is not available, your code should use 
GetNextEvent to retrieve events. If your code uses Get NextEvent, it should also 
call SystemTask to allow desk accessories to perform periodic actions. However, 
your code should always use WaitNextEvent if it is available, rather than 
GetNextEvent. If your application calls WaitNextEvent, it should not call the 
SystemTask procedure. 

















The event loop shown in Listing 2-2 calls an application-defined procedure, DoEvent, to 
determine what kind of event the call to WaitNextEvent retrieved. Listing 2-3 defines a 
simple DoEvent procedure. The DoEvent procedure examines the value of the what 
field of the event record to determine the type of event received and then calls an 
appropriate application-defined routine to further process the event. 
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Listing 2-3 Processing events 





PROCEDURE DoFvent (event: EventRecord); 











VAR 
window: WindowPtr; 
activate: Boolean; 
BEGIN 
CASE event.what OF 





mouseDown: 

DoMouseDown (event) ; 
mouseUp: 

DoMouseUp (event) ; 
keyDown, autoKey: 


DoKeyDown (event) ; 





activateEvt: 








BEGIN 
window := WindowPtr(event.message) ; 
activate := BAnd(event.modifiers, activeFlag) <> 0; 


DoActivate (window, activate, event); 
END; 
updateEvt: 








DoUpdate (WindowPtr (event.message) ); 
diskEvt: 

DoDiskEvent (event) ; 

osEvt: 





DoOSEvent (event) ; 
kHighLevelEvent: 











DoHighLevelEvent (event) ; 
END; {of case} 
END; 


The next sections describe how to set the event mask, handle events in dialog boxes, 
and create your application’s 'SIZE"' resource. Following sections show code that can 
handle each kind of event. 


Setting the Event Mask 


Several of the Event Manager routines can be restricted to operate on a specific event 
type or group of types. You do this by specifying the event types you want your 
application to receive, thereby disabling (or “masking out”) the events you are not 
interested in receiving. To specify which event types an Event Manager routine governs, 
you supply a parameter known as an event mask. 


The event mask is an integer with one bit position for each event type. If the bit 
representing a particular event type is set, then the Event Manager returns events of 
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that type. If the bit is set to 0, the Event Manager does not return events of that type. To 
accept all types of events, set every bit of the event mask to 1. You can do this using the 
constant everyEvent. 








CONST everyEvent = -l1; {every event} 


Figure 2-6 shows the bits corresponding to each event type in the event mask. 


Figure 2-6 The event mask 
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You can use these constants when referring to the bits in the event mask that correspond 
to each individual event type: 





CONST mDownMask = 2; {mouse-down event (bit 1)} 
mUpMask = 4; {mouse-up event (bit 2) } 
keyDownMask = 8; {key-down event (bit 3) } 
keyUpMask = 16; {key-up event (bit 4) } 
autoKeyMask = 32; {auto-key event (bit 5) } 
updateMask = 64; {update event (bit 6) } 
diskMask = 128; {disk-inserted event (bit 7) } 
activMask = 256; {activate event (bit 8) } 
highLevelEventMask = 1024; {high-level event (bit 10) } 
osMask = -—32768; {operating-system event (bit 15) } 
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You can select any subset of events by adding or subtracting these constants. For 
example, you can use this code to accept only high-level events and mouse-down events 
and mask out all other events: 








myErr := WaitNextEvent (highLevelEventMask + mDownMask, myEvent, 
mySleep, myMRgnHnd) ; 





The everyEvent constant indicates that you wish to receive every type of event. To 
accept all events except mouse-up events, you can use the code: 














myErr := WaitNextEvent (everyEvent - mUpMask, myEvent, mySleep, 





myMRgnHnd) ; 


Masking out specific types of events does not remove those events from the event 
stream. If a type of event is masked out, the Event Manager simply ignores it when 
reporting events from the event stream. Note that you cannot mask out null events by 
setting the event mask. The Event Manager always returns a null event if no other events 
are pending. However, if you do not want the Event Manager to report null events to 
your application when it is in the background, you can set the cannotBackground flag 
in your application’s 'SIZE' resource. 








In most cases you should always use everyEvent as your event mask. The user expects 
most applications to respond to keyboard, mouse, update, and other events. 


The types of events returned to your application are also affected by the system event 
mask. The Event Manager maintains a system event mask for each application. The 
system event mask controls which low-level event types get posted in the Operating 
System event queue. The Event Manager uses the system event mask of the current 
process (the process that is currently executing and the process associated with the 
CurrentA5 global variable) when determining which low-level events to post in the 
Operating System event queue. The system event mask is an integer with 1 bit for 

each corresponding low-level event type. These constants refer to the bits that represent 
the corresponding low-level event types in the system event mask: 


CONST mDownMask = 2; {mouse-down (bit 1)} 
mUpMask = 4; {mouse-up (bit 2) } 
keyDownMask = 8; {key-down (bit 3)} 
keyUpMask = 16; {key-up (bit 4) } 
autoKeyMask = 32; {auto-key (bit 5) } 
diskMask = 128; {disk-inserted (bit 7) } 


When a low-level event (other than an update or activate event) occurs, the Operating 
System Event Manager posts the low-level event in the Operating System event queue 
only if the bit corresponding to the low-level event type is set in the system event mask 
of the current process. When your application starts, the Operating System initializes the 
system event mask of your application to post mouse-up, mouse-down, key-down, 
auto-key, and disk-inserted events in the Operating System event queue. Thus, the 
system event mask has this initial setting: 





systemEventMask := everyEvent - keyUpMask; 
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Your application should not change the system event mask except to enable key-up 
events if your application needs to respond to key-up events. (Most applications ignore 
key-up events.) If your application needs to receive key-up events, you can change the 
system event mask using the Operating System Event Manager procedure 
SetEventMask. Note that your application cannot rely on receiving key-up events 
when it is not the current process. For example, if your application is the foreground 
(and current) process and a minor switch occurs, the Event Manager uses the system 
event mask of the background process (now the current process) when posting low-level 
event types. When your application becomes the current process again, the Event 
Manager uses the system event mask of your application when posting low-level events. 





Handling Events in a Dialog Box 


If your application uses alert boxes, modal dialog boxes, movable modal dialog boxes, 
or modeless dialog boxes, you need to make sure your application handles events for 
them appropriately. 


To display and handle events in alert boxes, you use the Dialog Manager functions 
Alert, NoteAlert, CautionAlert,and StopAlert. The Dialog Manager handles all 
of the events generated by the user until the user clicks a button (typically the OK or 
Cancel button). When the user clicks the OK or Cancel button, the alert box functions 
highlight the button that was clicked, close the alert box, and report the user’s selection 
to your application. Your application is responsible for performing the appropriate 
action associated with that button. 


For modal dialog boxes, you can use the Dialog Manager procedure ModalDialog. The 
Dialog Manager handles most of the user interaction until the user selects an item. The 
ModalDialog procedure then reports that the user selected an enabled item, and your 
application is responsible for performing the action associated with that item. Your 
application typically calls ModalDialog repeatedly, responding to clicks on enabled 
items as reported by ModalDialog, until the user selects OK or Cancel. 


For alert boxes and modal dialog boxes, you should also supply an event filter function 
as one of the parameters to the alert box functions or ModalDialog procedure. As the 
user interacts with the alert or modal dialog box, these functions pass events to your 
event filter function before handling each event. Your event filter function can handle 
any events not handled by the Dialog Manager or, if necessary, can choose to handle 
events normally handled by the Dialog Manager. For more information on filter 
functions for alert and dialog boxes, see the chapter “Dialog Manager” in this book. 


To handle events in movable modal dialog boxes, you can use the Dialog Manager 
functions IsDialogEvent and DialogSelect or you can use other Toolbox routines 
to handle events without using the Dialog Manager. 


For modeless dialog boxes, you can choose to handle events in them using an approach 
similar to the one you use to handle events in other windows; that is, when you receive 
an event, you first determine the type of event that occurred and then take the 
appropriate action based on the type of window that is in front. If a modeless dialog box 
is in front, you can provide code that takes any actions specific to that modeless dialog 
box and call the DialogSelect function to handle any events that your code doesn’t 
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handle. This is the approach used throughout this chapter. Alternatively, you can choose 
to call the IsDialogEvent function in your event loop. If you do this, you can use the 
IsDialogEvent function to determine whether the event involves a modeless dialog 
box that belongs to your application. If the event involves a modeless dialog box 
(including null events) and a modeless dialog box is active, IsDialogEvent returns 
TRUE. Otherwise, IsDialogEvent returns FALSE. 




















If IsDialogEvent returns TRUE, your application can check to see what type of event 
occurred and, depending on the type of event, it can choose to handle the event itself. 


Regardless of the approach you use, if your application chooses not to handle the event, 
it should call DialogSelect. The DialogSelect function handles events for 
modeless dialog boxes (including null events). It also blinks the caret in editable text 
items when necessary. 


For more information on the DialogSelect function and events in dialog boxes, see 
the chapter “Dialog Manager” in this book. 


Creating a Size Resource 


Your application should include a size ('SIZE') resource. You use a 'SIZE' resource to 
inform the Operating System about the memory size requirements for your application 
so that the Operating System can set up a partition of the appropriate size for your 
application. You also use the 'SIZE"' resource to indicate certain scheduling options to 
the Operating System, such as whether your application can accept suspend and 
resume events. 


You can also specify additional information in the 'SIZE' resource in System 7, 
indicating whether your application is 32-bit clean, whether your application supports 
stationery documents, whether your application uses TextEdit’s inline input services, 
whether your application wishes to receive notification of the termination of any applica- 
tions it has launched, and whether your application wishes to receive high-level events. 





A 'SIZE' resource consists of a 16-bit flags field, followed by two 32-bit size fields. The 
flags field specifies operating characteristics of your application, and the size fields 
indicate the minimum and preferred partition sizes for your application. The minimum 
partition size is the actual limit below which your application will not run. The 
preferred partition size is the memory size at which your application can run most 
effectively and that the Operating System attempts to secure upon launch of your 
application. If that amount of memory is unavailable, your application is placed into 

the largest contiguous block available, provided that it is larger than the specified 
minimum size. 


Note 

If the amount of available memory is between the minimum and the 
preferred sizes, the Finder displays a dialog box asking if the user wants 
to run the application using the amount of memory available. If your 
application does not have a 'SIZE' resource, it is assigned a default 
partition size of 512 KB and the Process Manager uses a default value 

of FALSE for all specifications normally defined by constants in the 
flags field. 
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When you define a 'SIZE' resource, you should give it a resource ID of —-1. A user can 
modify the preferred size in the Finder’s information window for your application. If the 
user does alter the partition size, the Operating System creates anew 'SIZE"' resource 
having a resource ID of 0. At application launch time, the Process Manager looks for a 


'SIZI 
resource with ID -1. This new 'S12Z! 
any of the other settings in the resource. 











E' resource with ID 0; if this resource is not found, it uses your original 'SIZE' 
E.' resource is also created when the user modifies 


When creating a 'SIZE"' resource, you first need to determine the various operating 
characteristics of your application. For example, if your application has nothing useful to 
do when it is in the background, then you should not set the canBackground flag. 
Similarly, if you have not tested your application in an environment that uses all 32 bits 
of a handle or pointer for memory addresses, then you should not set the 
is32BitCompatible flag. 


Listing 2-4 shows the Rez input for asample 'SIZE" resource. (Rez is a resource 
compiler available with the MPW environment.) 


Listing 2-4 
resource 'SIZE' (-1) { 
reserved, 


hi 


accept SuspendResumeEvents, 


reserved, 


canBackground, 


doesActivateOnFGSwitch, 


backgroundAndForeground, 


dontGetFrontClicks, 


ignoreAppDiedEvents, 
is32BitCompatible, 
isHighLevelEventAware, 
localAndRemoteHLEvents, 
isStationeryAware, 
dontUseTextEditServices, 


reserved, 
reserved, 
reserved, 
kPrefSize * 1024, 
kMinSize * 1024 
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The Rez input fora sample 'SIZE' resource 


/*reserved*/ 





/*accepts suspend&resume events*/ 
/*reserved*/ 

/*can use background null */ 

/* events*/ 

/*activates own windows in */ 

/* response to OS events*/ 
/*application has a user */ 

/* interface*/ 

/*don't return mouse events */ 

/* in front window on resume*/ 
/*doesn't want app-died events*/ 
/*works with 24- or 32-bit addr*/ 
/*supports high-level events*/ 
/*also remote high-level events*/ 
/*can use stationery documents*/ 
/*can't use inline input */ 

/* services*/ 

/*reserved*/ 

/*reserved*/ 

/*reserved*/ 

/*preferred memory size*/ 


/*minimum memory size*/ 
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The 'SIZE"' resource specification in Listing 2-4 indicates, among other things, that the 
application accepts suspend and resume events, does processing in the background 
using null events, activates or deactivates any windows as necessary in response to 
operating-system events, can execute in both the foreground and background, and 
doesn’t want to receive any mouse event associated with a resume event that was caused 
by the user clicking in the application’s front window. It also indicates that the 
application doesn’t want to receive Application Died events, can work in 24-bit or 32-bit 
addressing mode, does accept high-level events, including both local and network 
high-level events, does handle stationery documents, and doesn’t use TextEdit’s inline 
input services. In this example, the Rez-input file must define values for the constants 
kPrefSize and kMinSize; for example, if kPrefSize is set to 50, the preferred 
partition size is 50 KB. 





The numbers you specify as your application’s preferred and minimum memory sizes 
depend on the particular memory requirements of your application. Your application’s 
memory requirements depend on the size of your application’s static heap, dynamic 
heap, A5 world, and stack. (See “Introduction to Memory Management” in Inside 
Macintosh: Memory for complete details about these areas of your application’s partition.) 


The static heap size includes objects that are always present during the execution of your 
application—for example, code segments, Toolbox data structures for window records, 
and so on. 


Dynamic heap requirements come from various objects created on a per-document basis 
(which may vary in size proportionally with the document itself) and objects that are 
required for specific commands or functions. 


The size of the A5 world depends on the amount of global data and the number of 
intersegment jumps your application contains. 


The stack contains variables, return addresses, and temporary information. The size of 
the application stack varies among computers, so you should base your values for the 
stack size according to the stack size required on a Macintosh Plus computer (8 KB). 
The Process Manager automatically adjusts your requested amount of memory to 
compensate for the different stack sizes on different machines. For example, if you 
request 512 KB, more stack space (approximately 16 KB) will be allocated on machines 
with larger default stack sizes. 


Unfortunately, it is difficult to forecast all of these conditions with any great degree of 
reliability. You should be able to determine reasonably accurate estimates for the stack 
size, static heap size, A5 world, and jump table. In addition, you can use tools such as 
MacsBug’s heap-exploring commands to help you empirically determine your 
application’s dynamic memory requirements. 


See “The Size Resource” beginning on page 2-115 for additional information on the 
meaning of each of the fields and flags of a 'SIZE' resource. 


Handling Low-Level Events 


Low-level events include hardware-related occurrences stored in the Operating System 
event queue and activate and update events generated by the Window Manager. When 
your application receives a low-level event, your application needs to determine the type 
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of event and respond appropriately. The following sections discuss how to respond to 
mouse events, keyboard events (including certain specific keyboard events, such as 
when the user presses the Command key and period key at the same time), update 
events, activate events, disk-inserted events, and null events. 


Responding to Mouse Events 


Whenever the user presses or releases the mouse button, the Operating System Event 
Manager records the action in the Operating System event queue. These actions are 
stored in the event queue as mouse-down and mouse-up events. Your application can 
retrieve these events using the WaitNextEvent function. 


Events related to movements of the mouse are not stored in the event queue. The mouse 
driver automatically tracks the mouse and displays the cursor as the user moves the 
mouse. Therefore, the Operating System Event Manager does not report an event if the 
user simply moves the mouse. 


However, you can request that the Event Manager report mouse-moved events if the 
user moves the cursor out of a region that you specify to the WaitNextEvent function. 
For example, your application can use mouse-moved events in this way to change the 
shape of the cursor from an I-beam to an arrow when the user moves the cursor from a 
text area to the scroll bar of a window. 


The rest of this section describes how your application responds to mouse-down or 
mouse-up events. See “Responding to Mouse-Moved Events” beginning on page 2-62 
for specific details on mouse-moved events. 


The user expects that pressing the mouse button correlates to particular actions in an 
application. Your application is responsible for providing feedback or performing any 
actions in response to the user. For example, if the user presses the mouse button while 
the cursor is in the menu bar, your application should use the Menu Manager function 
MenuSelect to allow the user to choose a menu command. 


Your application can receive and respond to mouse-down and mouse-up events. Most 
applications respond to mouse-down events and use the routines of various managers 
(such as MenuSelect, DragWindow, TEClick, TrackBox, TrackGoAway, and 
TrackCont rol) to handle the corresponding mouse-up events. You can also provide 
code to respond to mouse-up events if it’s appropriate for your application. For example, 
if your application implements its own text-editing capabilities, you might let the user 
select lines of text by dragging the mouse and use mouse-up events to signal the end of 
the selection. 


In System 7, your application receives mouse-down events only when it is the 
foreground process and the user clicks in the menu bar, in a window belonging to your 
application, or in a window belonging to a desk accessory that was launched in your 
application’s partition. If the user clicks in a window belonging to another application, 
the Event Manager sends your application a suspend event and performs a major switch 
to the other application. 


When your application receives a mouse-down event, you need to first determine the 
location of the cursor at the time the mouse button was pressed (the mouse location) 
and respond appropriately. You can use the Window Manager function FindWindow to 
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find which of your application’s windows, if any, the mouse button was pressed in and, 
if applicable, to find which part of the window it was pressed in. The FindWindow 
function also reports whether the given mouse location is in the menu bar or, in some 
cases, in a window belonging to a desk accessory (if the desk accessory was launched in 
your application’s partition). 

The what field of the event record for a mouse event contains the mouseDown or 
mouseuUp constant to report that the mouse button was pressed or released. The 
message field is undefined. The when field contains the number of ticks since the 
system last started up. You can use the when field to compare how much time has 
elapsed between successive mouse events; for example, you might use this information 
to help detect mouse double clicks. 


The where field of the event record contains the location of the cursor at the time the 
mouse button was pressed or released. You can pass this location to the FindWindow 
function; the FindWindow function maps the given mouse location to particular areas 
of the screen. 


The modifiers field contains information about the state of the modifier keys at the 
time the mouse button was pressed or released. Your application can perform different 
actions based on the state of the modifier keys. For example, your application might let 
the user extend a selection or select multiple objects at a time if the Shift key was down 
at the time of the mouse-down event. 


Listing 2-5 shows code that handles mouse-down events. The DoMouseDown procedure 
is an application-defined procedure that is called from the DoEvent procedure. 
(Listing 2-3 on page 2-26 shows the DoEvent procedure.) 





Listing 2-5 Handling mouse-down events 


PROCEDURE DoMouseDown (event: EventRecord) ; 


VAR 
part: Integer; 
thisWindow: WindowPtr; 
BEGIN 


{map location of the cursor (at the time of mouse-down event) } 
{ to general areas of the screen} 
part := FindWindow(event.where, thisWindow) ; 


CAS 


ea) 





part OF {take action based on the mouse location} 


inMenuBar: {mouse down in menu bar, respond appropriately} 
BEGIN 
{first adjust marks and enabled state of menu items} 
MyAdjustMenus; 





{let user choose a menu command} 
DoMenuCommand (MenuSelect (event.where) ); 
END; 





inSysWindow: {cursor in a window belonging to a desk accessory} 
SystemClick (event, thisWindow) ; 
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inContent: {mouse down occurred in the content area of } 





{ one of your application's windows} 
IF thisWindow <> FrontWindow THEN 
BEGIN {mouse down occurred in a window other than the front } 





{ window—-make the window clicked in the front window, } 
{ unless the front window is movable modal} 
IF MyIsMovableModal (FrontWindow) THEN 
SysBeep (30) 
ELSE 
SelectWindow (thisWindow) ; 
END 
ELSE {mouse down was in the content area of front window} 





DoContentClick (thisWindow, event); 


inDrag: {handle mouse down in drag area} 
IF (thisWindow <> FrontWindow) AND 
(MyI sMovableModal (FrontWindow) ) 
THEN 
SysBeep (30) 
ELSE 
DragWindow(thisWindow, event.where, GetGrayRgn**.rgnBBox) ; 








inGrow: {handle mouse down in grow region} 
DoGrowWindow(thisWindow, event); 


inGoAway: {handle mouse down in go-away region} 
IF TrackGoAway (thisWindow, event.where) THEN 
DoCloseCmd; 


inZoomIn, inZoomOut: {handle mouse down in zoom box region} 
IF TrackBox(thisWindow, event.where, part) THEN 
DoZoomWindow(thisWindow, part); 
END; {end of CASE} 
END; {of DoMouseDown } 








When your application retrieves a mouse-down event, call the Window Manager 
function F indWindow to map the location of the cursor to particular areas of the screen. 
Given a mouse location, the FindWindow function returns as its function result a value 
that indicates whether the mouse location is in the menu bar, in one of your application’s 
windows, or, in some cases, in a desk accessory window. If the mouse location is in an 
application window, the function result indicates which part of the window the mouse 
location is in. You can test the function result of FindWindow against these constants to 
determine the mouse location at the time of the mouse-down event: 


CONST inDesk = 0;{none of the following} 
inMenuBar = 1;{in the menu bar} 


inSysWindow = 2;{in a desk accessory window} 
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inContent = 3;{anywhere in content region except the } 





{ grow region if the window is active, } 
{ anywhere in content region including the } 
{ grow region if the window is inactive} 


inDrag = 4;{in drag (title bar) region} 

inGrow = 5;{in grow region (active window only) } 
inGoAway = 6;{in go-away region (active window only) } 
inZoomIn = 7;{in zoom-in region (active window only) } 
inZoomOut = 8;{in zoom-out region (active window only) } 


The FindWindow function reports the inDesk constant if the mouse location is not in 
the menu bar, desk accessory window, or any window of your application. For example, 
the FindWindow function may report this constant if the location of the cursor is inside 
a window frame but not in the drag region or go-away region of the window; your 
application seldom receives the inDesk constant. 





If FindWindow returns the inMenuBar constant, the mouse location is in the menu bar. 
In this case your application should first adjust its menus. The application-defined 
MyAdjustMenus procedure adjusts its menus—enabling and disabling items and 

setting marks—based on the context of the active window. For example, if the active 
window is a document window that contains a selection, your application should enable 
the Cut and Copy commands in the Edit menu, add marks to the appropriate items in 
the Font, Size, and Style menus, and adjust any other menu items accordingly. After 
adjusting your application’s menus, call the Menu Manager function MenuSelect, 
passing it the location of the mouse, to allow the user to choose a menu command. The 
MenuSelect function handles all user interaction until the user releases the mouse 
button. The MenuSelect function returns as its function result a long integer indicating 
the menu selection made by the user. As shown in Listing 2-5 on page 2-34, the 
DoMouseDown routine calls an application-defined routine, DoMenuCommand, to 
perform the menu command selected by the user. See the chapter “Menu Manager” in 
this book for a listing that gives the code for the MyAdjustMenus and DoMenuCommand 
routines and for more information about responding to specific menu commands. 


In System 7, the FindWindow function seldom returns the inSysWindow constant. The 
F indWindow function returns this constant only when a mouse-down event occurred 

in a desk accessory that was launched in the application’s partition. Normally, if the 
user clicks in a desk accessory’s window, the Event Manager sends your application a 
suspend event and brings the desk accessory to the foreground. From that point on, 
mouse-down events and other events are handled by the desk accessory until the user 
again clicks in one of your application’s windows. 


If FindWindow does return the inSysWindow constant, the mouse location is in a 
window belonging to a desk accessory that was launched in your application’s 
partition. In this case, your application should call the Syst emClick procedure. The 
SystemClick procedure routes the event to the desk accessory as appropriate. If the 
mouse button was pressed while the cursor was in the content region of the desk 
accessory’s window and the window is inactive, SystemClick makes it the active 
window. It does this by sending your application an activate event to deactivate its front 
window and directing an event to the desk accessory to activate its window. 
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F indWindow can return any of the constants inContent, inDrag, inGrow, inGoAway, 
inZoomIn, or inZoomOut if the given mouse location is in your application’s active 
window. If the cursor is in the content area, your application should perform any actions 
appropriate to your application. Note that scroll bars are part of the content region. In 
most cases, if the cursor is in the content area, your application first needs to determine 
whether the mouse location is in the scroll bar or any other controls and then respond 
appropriately. The DoMouseDown procedure calls the application-defined procedure 
DoContentClick to handle mouse-down events in the content area of the active 
window. If your application needs to determine whether the mouse-down event caused 
a foreground switch (and you set the get FrontClicks flag in your application’s 
"SIZE" resource), your DoContentClick procedure can test bit 0 in the modifiers 
field of the event record (normally your application does not test for this condition). 

See the chapter “Control Manager” in this book for an example DoContentClick 
procedure and for detailed information on implementing controls in your 

application’s windows. 


If the mouse location is in any of the other specified regions of an active application 
window, your application should perform the action corresponding to that region. 
For example, if the cursor is in the drag region, your application should call the 
Window Manager procedure DragWindow to allow the user to drag the window to 
a new location. 


If the mouse location is in an inactive application window, FindWindow can return the 
inContent or inDrag constant, but does not distinguish between any other areas of 
the window. In this case, if FindWindow reports the inContent constant, your 
application should bring the inactive window to the front using the SelectWindow 
procedure (unless the active window is a movable modal dialog box). If the active 
window is a movable modal dialog box, then your application should use the SysBeep 
procedure to play the system alert sound rather than activating the selected window. 
Also, if your application interprets the first mouse click in an inactive window as a 
request to activate the window and perform an action, you can process the event again. 
However, note that most users expect the first click in an inactive window to activate 
the window without performing any additional action. If FindWindow reports inDrag 
for an inactive application window, your application should call the DragWindow 
procedure to allow the user to drag the window to a new location (unless the active 
window is a movable modal dialog box, in which case your application should simply 
play the system alert sound). 








If you’re using TextEdit to handle text editing and call TEClick, TEClick automatically 
interprets mouse double clicks appropriately, including allowing the user to select a 
word by double-clicking it. Your application must provide the means to allow double- 
clicking in this manner in all other contexts. 


You can detect mouse double clicks by comparing the time and location of a mouse-up 
event with that of the immediately following mouse-down event. The GetDb1Time 
function returns the recommended difference in ticks that should exist between the 
occurrence of a mouse-up and mouse-down event for those two mouse events to be 
considered a double click. 
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You should interpret mouse events as a double click if both of these conditions are true: 


m The times of the mouse-up event and mouse-down event differ by a number of ticks 
less than or equal to the value returned by the GetDb1Time function. 


m The locations of the two mouse-down events separated by the mouse-up event are 
sufficiently close to each other. How you determine this value depends on your 
application and the context in which the mouse-down events occurred. For example, 
in a word-processing application, you might consider two mouse-down events a 
double click if the mouse locations both mapped to the same character, whereas in a 
graphics application you might consider it a double click if the sum of the horizontal 
and vertical difference between the two mouse locations is no more than five pixels. 


The Event Manager also provides other routines that give information about the mouse. 
You can find the current mouse location using the GetMouse procedure. You can 
determine the current state of the mouse button using the Button, StillDown, and 
WaitMouseUp functions. See “Reading the Mouse” beginning on page 2-108 for detailed 
information on these routines. 


Responding to Keyboard Events 


Your application can receive keyboard events to notify you when the user has pressed 
or released a key or continued to hold down a key. When the user presses a key, the 
Operating System Event Manager stores a key-down event in the Operating System 
event queue. Your application can retrieve the event from the queue; determine which 
key was pressed; determine which modifier keys, if any, were pressed at the time of the 
event; and respond appropriately. Typically, your application provides feedback by 
echoing (displaying) the glyph representing the character generated by the pressed key 
on the screen. 


When the user holds down a key for a certain amount of time, the Event Manager 
generates auto-key events. The Event Manager generates an auto-key event after a 
certain initial delay (the auto-key threshold) has elapsed since the original key-down 
event. The Event Manager generates subsequent auto-key events whenever a certain 
repeat interval (the auto-key rate) has elapsed since the last auto-key event and while 
the original key is still held down. The user can set the initial delay and rate of repetition 
using the Keyboard control panel. The default value for the auto-key threshold is 

16 ticks, and the default value for the auto-key rate is 4 ticks. Current values of the auto- 
key threshold and auto-key rate are stored in the system global variables KeyThresh 
and KeyRepThresh. 


In addition to getting keyboard events when the user presses or releases a key, you can 
directly read the keyboard (and keypad) using the Get Keys procedure. 


When the user presses a key or a combination of keys, your application should respond 
appropriately. Your application should follow the guidelines in Macintosh Human 
Interface Guidelines for consistent use of and response to keyboard events. For example, 
your application should allow the user to choose a frequently used menu command by 
using a keyboard equivalent for that menu command—usually a combination of the 
Command key and another key. Your application should also respond to the user 
pressing the arrow keys, Shift key, or other keys according to the guidelines provided 
in Macintosh Human Interface Guidelines. 
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Also note that certain keyboards have different physical layouts or contain additional 
keys, such as function keys. If your application supports function keys or other special 
keys, you should follow the guidelines in Macintosh Human Interface Guidelines when 
determining what action to take when the user presses one of these keys. 


Certain keystroke combinations are handled by the Event Manager and not returned to 
your application. If the user holds down the Command and Shift keys while pressing a 
numeric key to produce a special effect, that special effect occurs. Apple provides three 
standard Command-Shift-number key sequences. The standard Command-Shift- 
number key sequences are 1 for ejecting the disk in the internal drive, 2 for ejecting the 
disk in a second internal drive or for ejecting the disk in an external drive if the 
computer has only one internal drive, and 3 for taking a snapshot of the screen and 
storing it as a TeachText document on the startup volume. 


The action corresponding to a Command-Shift-number key sequence is implemented 
as a routine that takes no parameters and is stored in an 'FKEY' resource with a resource 
ID that corresponds to the number that activates it. Apple reserves 'FKEY' resources 
with resource IDs 1 through 4 for its own use; if you provide an 'FKEY' resource, use a 
resource ID between 5 and 9. 








You can disable the Event Manager’s processing of Command-Shift-number key 
sequences for numbers 3 through 9 by setting the system global variable ScrDmpEnb 
(a byte) to 0. However, in most cases you should not disable the Event Manager’s 
processing of these events. 


The what field of the event record for a keyboard-related event contains either the 
keyDown or keyUp constant to indicate that the key was pressed or released, or the 
autokey constant to indicate that the key is being held down. 


The Event Manager sets the system event mask of your application to accept all events 
except key-up events. Most applications ignore key-up events. If your application needs 
to receive key-up events, you can change the system event mask of your application 
using the Operating System Event Manager procedure SetEventMask. 





In the low-order word the message field contains the character code and virtual key 
code that corresponds to the key pressed by the user. 


The virtual key code represents the key pressed or released by the user; this value is 
always the same for a specific physical key on a particular keyboard. For example, on 
the Apple Keyboard II, ISO layout, the virtual key code for the fifth key to the right 
of the Tab key (the key labeled “T” ) is always $11, regardless of which modifier keys 
are also pressed. 


To determine the virtual key code that corresponds to a specific physical key, system 
software uses a hardware-specific key-map ('KMAP ') resource that specifies the virtual 
key codes for a particular keyboard. After determining the virtual key code of the key 
pressed by the user, system software uses a script-specific keyboard-layout ('KCHR') 
resource to map a virtual key code to a specific character code. Any given script system 
has one or more 'KCHR' resources. For example, a particular computer might contain 
the French 'KCHR' resource in addition to the standard U.S. 'KCHR' resource. In this 
situation, the current 'KCHR"' resource determines whether virtual key codes are 
mapped to the French or U.S. character set. 


Using the Event Manager 2-39 


2-40 


CHAPTER 2 


Event Manager 


The character code represents a particular character. The character code that is generated 
depends on the virtual key code, the state of the modifier keys, and the current 'KCHR' 
resource. For example, the U.S. 'KCHR' resource specifies that for the virtual key code 
$2D (the fifth key to the left of the Shift key and labeled “N” on an Apple Keyboard II, 
Domestic layout), the character code is $6E when no modifier keys are pressed; the 
character code is $4E when this key is pressed in combination with the Shift key. 
Character codes for the Roman script system are specified in the extended version of 
ASCII (the American Standard Code for Information Interchange). 


The message field contains additional information for ADB keyboards. The low-order 
byte of the high-order word contains the ADB address of the keyboard where the 
keyboard event occurred. Figure 2-7 shows the structure of the message field of the 
event record for keyboard events. 


Figure 2-7 The message field of the event record for keyboard events 





Usually your application uses the character code, rather than the virtual key code, when 
responding to keyboard events. You can use these two constants to access the virtual key 
code and character code in the message field: 


CONST charCodeMask = SOOOQOOOOFF; {mask for character code} 
keyCodeMask SOOOOFFO0; {mask for virtual key code} 


The when field contains the number of ticks since the system last started up. You can 
use the when field to compare how much time has expired between successive 
keyboard events. 


The where field of the event record contains the location of the cursor at the time the key 
was pressed or released. You typically disregard the mouse location when processing 
keyboard events. 


The modifiers field contains information about the state of the modifier keys at the 
time the key was pressed or released. Your application can perform different actions 
based on the state of the modifier keys. For example, your application might perform an 
action associated with a corresponding menu command if the Command key was down 
at the time of the key-down event. 


System software can support a number of different types of keyboards, for example, the 
Apple Keyboard II, the Apple Extended keyboards, or other keyboards. The system 
software uses various keyboard resources and international resources to manage 
different types of keyboards. Figure 2-8 illustrates how system software maps keys to 
character codes. 
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Figure 2-8 Keyboard translation 
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When a user presses or releases a key on the keyboard, the keyboard generates a raw 
key code. The system software uses a 'KMAP' resource to map the raw key code to a 
hardware-independent virtual key code and to set bits indicating the state of the 
modifier keys. A 'KMAP' resource specifies the physical arrangement of a particular 
keyboard and indicates the virtual key codes that correspond to each physical key. 


If the optional key-remap ('it1k’') resource is present, the system software remaps the 
virtual key codes and modifier state for some key combinations on certain keyboards 
before using the 'KCHR' resource. The 'it1k' resource can reintroduce hardware 
dependence because certain scripts, languages, and regions need subtle differences in 
layout for specific keyboards. If present, the 'it1k' resource affects only a few keys. 


After mapping the virtual key code and the state of the modifier keys through an 
optional 'it1k' resource, the system software uses a 'KCHR' resource to produce the 
character code representing the key that was pressed or released. The 'KCHR' resource 
specifies how to map the setting of the modifier keys and a virtual key code toa 
character code. 
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After mapping the key, the Event Manager returns the virtual key code and the character 
code in the message field of the event record. 


Figure 2-9 shows the virtual key codes as specified by the 'KMAP ' resource for the 
Apple Keyboard II, ISO layout. The labels for the keys on the keyboard are shown using 
the U.S. keyboard layout. The virtual key codes are shown in hexadecimal. 


Figure 2-9 Virtual key codes for the Apple Keyboard II, ISO layout 





Figure 2-10 shows the virtual key codes as specified by the 'KMAP ' resource for the 

Apple Extended Keyboard II, one that uses the Domestic (ANSI) layout, and one that 
uses the ISO layout. The labels for the keys on the ISO keyboard are shown using the 
French keyboard layout. The virtual key codes are shown in hexadecimal. 


If a user of an Apple Extended Keyboard II (using the U.S. 'KCHR' resource) presses the 
key labeled “C” and no modifier keys, the system software maps this through the 'KMAP' 
and 'KCHR' resources to produce a virtual key code of $08 and the character code $63 (the 
character “c”) in the message field of the event record. If the user presses the key 
labeled “C” and the Option key, then the system software maps this to virtual key code 
$08 and the character code $8D (the character “¢”) in the message field. 


As another example, if a user of an Apple Extended Keyboard II, Domestic layout, is 
using the U.S. 'KCHR' resource and presses the key labeled “M” the system software 
maps this through the 'KMAP' and 'KCHR' resources to produce a virtual key code of $2E 
and the character code $6D (the character “m”) in the message field of the event record. 


If a user of an Apple Extended Keyboard I, ISO layout, is using the French 'KCHR' 
resource and presses the key labeled “M” the system software maps this through the 
'KMAP' and 'KCHR' resources to produce a virtual key code of $29 and the character 
code $6D (the character “m”) in the message field of the event record. 


See Inside Macintosh: Text for additional information about the keyboard resources and 
how the Script Manager manages various scripts. 
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Virtual key codes for the Apple Extended Keyboard II 


Figure 2-10 
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Listing 2-6 shows code that handles key-down and auto-key events. The DoKeyDown 
procedure is an application-defined procedure that is called from the DoEvent 
procedure. (Listing 2-3 on page 2-26 shows the DoEvent procedure.) 





Listing 2-6 Handling key-down and auto-key events 


PROCEDURE DoKeyDown (event: EventRecord) ; 
VAR 
key: Char; 
BEGIN 
key := CHR(BAnd(event.message, charCodeMask) ); 
IF BAnd(event.modifiers, cmdKey) <> 0 THEN 
BEGIN {Command key down} 
IF event.what = keyDown THEN 
BEGIN {first enable/disable/check menu items as needed-- } 
{ the MyAdjustMenus procedure adjusts the menus } 




















{ as appropriate for the current window} 
MyAdjustMenus; 
DoMenuCommand (MenukKey (key)); {handle the menu command} 
END; 





END 
ELSE 
MyHandleKeyDown (event) ; 
END; 


The DoKeyDown procedure in Listing 2-6 first extracts the character code of the key 
pressed from the message field of the event record. It then checks the modifiers field 
of the event record to determine if the Command key was pressed at the time of the 
event. If so, and if the event is a key-down event, the code calls the application-defined 
procedure MyAdjustMenus, and then calls another application-defined routine, 
DoMenuCommand, to perform the menu command associated with that key. (The 
MyAdjustMenus procedure adjusts the menus appropriately, and according to whether 
the current window is a document window or modeless dialog box. See the chapter 
“Menu Manager” in this book for code that defines the MyAdjustMenus procedure.) 
Otherwise, the code calls the application-defined procedure MyHandleKeyDown to 
handle the event. 


Listing 2-7 shows the application-defined routine MyHandleKeyDown. 


Listing 2-7 Handling key-down events 


PROCEDURE MyHandleKeyDown (event: EventRecord) ; 
VAR 

key: Char; 

window: WindowPtr; 
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myData: MyDocRecHnd; 

te: TEHandle; 

windowType: Integer; 
BEGIN 

window := FrontWindow; 


{determine the type of window--document, modeless, etc. } 











windowType := MyGetWindowType (window) ; 

IF windowType = kMyDocWindow THEN 

BEGIN 
key := CHR(BAnd(event.message, charCodeMask) ); 
IF window <> NIL THEN 
BEGIN 


IF key = char(kTab) THEN {handle special characters} 
MyDoTab (event ) 








ELSE 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
te := myData**’%.editRec; 
IF 
(te**.teLength - (te**.selEnd - te**.selStart) + 1 
< kMaxTELength) THEN 
BEGIN 
TEKey (key, te); {insert character in document } 
MyAdjustScrollBars (window, FALSE); 
MyAdjustTE (window) ; 
myData®**.windowDirty := TRUE; 
END; 
END; 
END; 
END 
ELSE 


MyHandleKeyDownInModeless (event, windowType) ; 





END; 


The MyHandleKeyDown procedure in Listing 2-7 handles key-down events in any 
window of the application. For document windows, the code inserts the character 
represented by the key pressed by the user into the active document. It first finds the 
active document using the FrontWindow function, then handles the event as 
appropriate for the document window. For example, it treats the Tab key as a special 
character and calls an application-defined routine, MyDoTab, to handle this character 
appropriately for the document. For all other keys directed to the document window, the 
code gets the edit record associated with the document, and then it simply inserts the 
character into the document, using the TextEdit TEKey procedure. It also calls two other 
application-defined routines, MyAdjustScrollBars andMyAdjustTE, to update the 
document and edit record. 
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The MyHandleKeyDown procedure calls an application-defined routine, 
MyHandleKeyDownInModeless, to handle key-down events in modeless dialog boxes. 
See the chapter “Dialog Manager” in this book for more information on handling events 
in dialog boxes. 


Scanning for a Cancel Event 


Your application should allow the user to cancel a lengthy operation by using the 
Command-period combination. Your application can implement this cancel operation by 
periodically examining the state of the keyboard using the Get Keys procedure, or your 
application can scan the event queue for a keyboard event. 


Listing 2-8 shows an application-defined function that scans the event queue for any 
occurrence of a Command-period event. 


The UserDidCance1l function in Listing 2-8 first checks to see if the user changed the 
script. The application maintains a global variable, gcurrentKeyScript, that keeps 
track of this information. The application also uses a global variable, gPeriodKeyCode, 
to hold the key code that maps to the period key according to the current script. If the 
current script has changed, the UserDidCancel function calls an application-defined 
routine, MySet PeriodKeyCode, to change the value of the gperiodKeyCode global 
variable as necessary. 





The UserDidCance1l function then determines whether A/UX is running. You must 
use a different method to scan the event queue if A/UX is running. This code uses 

an application-defined function called MyCheckAUXEvent Queue to search for a 
Command-period event if A/UX is running. Otherwise, the code checks the what field 
for a key-down event. If it finds a key-down event, it then checks the message field 
to determine whether the user pressed the period key and checks the modifiers 
field to determine whether the user also pressed the Command key. If it finds the 
Command-period combination, it sets the foundEvent variable to TRUE and returns 
this value. Otherwise, it looks at the next entry in the queue and continues to search the 
queue until it either finds a Command-period event or reaches the end of the queue. 





Listing 2-8 Scanning for a Command-period event 


FUNCTION UserDidCancel: Boolean; 




















VAR 
foundEvent: Boolean; 
eventQPtr: EVQEIPtr; 
eventQHdr: QHdrPtr; 
keyCode: LongInt; 
isCmdKey: LongInt; 
BEGIN 
foundEvent := FALSE; {assume the event is not there} 








{Check to see if the script has changed} 


IF (gCurrentKeyScript <> GetEnvirons (smKeyScript)) THEN 


MySetPeriodKeyCode; {set gPeriodKeyCode to match new script} 
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IF (GetAUXVersion > 0) THEN {if A/UX is running use this method} 
foundEvent := MyCheckAUXEventQueue (gPeriodKeyCode, cmdKey) 
ELSE 
BEGIN {scan event queue} 
eventQHdr := GetEvQHdr; {get the event queue header} 
eventQPtr := EvQE1Ptr (eventQHdr%.qHead) ; {get first entry} 
WHILE (eventQPtr <> NIL) AND (NOT(foundEvent)) DO 
BEGIN {look for key-down event} 
IF (eventQPtr®*.evtQWhat = keyDown) THEN {found key-down event, } 
BEGIN { look for Command-period} 
keyCode := BAND(eventOPtr®.evtQMessage, keyCodeMask) ; 
keyCode := BSR(keyCode, 8); 
isCmdKey := BAND(eventQPtr®.evtQModifiers, cmdKey) ; 
IF isCmdKey <> 0 THEN {Command key was pressed} 
IF keyCode = gPeriodKeyCode THEN 
foundEvent := TRUE; {key pressed was '.'} 
END; {of found key-down} 
IF (NOT foundEvent) THEN {go to next entry} 
eventQPtr := EvQE1Ptr(eventQPtr’.qLink) ; 
END; {of while} 
END; {of scan event queue} 
UserDidCancel := foundEvent; {return result of search} 
END; 


Responding to Update Events 


The Event Manager reports update events to your application whenever one of your 
application’s windows needs updating. Upon receiving an update event, your applica- 
tion should update the contents of the specified window. Your application can call the 
Window Manager procedure BeginUpdate, draw the window’s contents, and then call 
EndUpdate when your application has finished updating the window’s contents. 





Your application can also let the Window Manager automatically update the contents of 
a window by supplying in the window record a handle to a picture that contains the 
contents of the window. This technique is generally useful only for windows that contain 
static information that doesn’t change or can’t be edited. For example, if your application 
provides a window that always displays a picture of the earth, you can supply the 
handle to the picture, and the Window Manager automatically updates the window as 
needed, without sending your application an update event. In most cases, your 
application needs to perform the update itself. 


The Window Manager maintains an update region for each window. The Window 
Manager keeps track of all areas in a window’s content region that need to be redrawn 
and accumulates them in the window’s update region. When an application calls 
WaitNextEvent orEventAvail (or GetNextEvent), the Event Manager checks to 
see if any windows have an update region that is not empty. If so, the Event Manager 
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reports update events to the appropriate applications; any applications with windows 
that require updating receive the necessary update events according to the normal 
processing of events. 


If more than one window needs updating, the Event Manager issues update events for 
the frontmost window first. This means that updating of windows occurs in 
front-to-back order, which is what the user expects. 


When one of your application’s windows needs to be updated, the Window Manager 
calls the window definition function of that window, requesting that it draw the window 
frame. The Window Manager then generates an update event for that window. The 
Event Manager reports any update events for your application’s windows to your 
application, and your application should update the window contents as necessary. 


In response to an update event, your application should first call the BeginUpdate 
procedure. The BeginUpdate procedure temporarily replaces the visible region of the 
window’s graphics port (that part of the window that is visible on the screen) with the 
intersection of the visible region and update region of the window. The BeginUpdate 
procedure then clears the update region of the window—preventing the update event 
for this occurrence from being reported again. 











After calling BeginUpdate, your application should draw the window’s contents, 
either entirely or in part. You can draw either the entire content region or only the area in 
the visible region. In either case, the Window Manager allows only what falls within the 
visible region to be drawn on the screen. (Because the BeginUpdate procedure 
intersects the visible region with the update region, the visible region at this point 
corresponds to any visible parts of the old update region.) 





The EndUpdate procedure restores the normal visible region of the window’s 
graphics port. 


Figure 2-11 shows how an application updates its windows. In this example, Window 1 
partially covers Window 2. When the user moves Window 1 so that more of Window 2 is 
exposed, the Window Manager requests the window definition function of the window 
to update the window frame, and accumulates the area requiring updating in the update 
region of the window. 


When the application receives an update event for this window, the message field of the 
event record contains a pointer to the window that needs updating. Your application can 
call BeginUpdate, draw the window’s contents, and then call EndUpdate. This 
completes the handling of the update event. 


Your application can receive update events when it is in the foreground or in the 
background. In the example shown in Figure 2-11, Window 1 and Window 2 could 
belong to the same application or different applications. In either case, the Event 
Manager reports an update event to the application whose window contents 

need updating. 
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Figure 2-11 Responding to an update event for a window 
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Your application should respond to update events or at least call the BeginUpdate 
procedure in response to an update event. If you do not call the BeginUpdate 
procedure, your application continues to receive update events for the window (until 

the update region is empty). You should always make sure that you match a call to 
BeginUpdate with a call to EndUpdate. By calling the BeginUpdate and EndUpdate 
procedures, you indicate to the Window Manager that you have updated the window 
and handled the update event. 
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Listing 2-9 shows an example of an application-defined routine that responds to 
update events. 


Listing 2-9 Responding to update events 





PROCEDURE DoUpdate (window: WindowPtr) ; 
VAR 
windowType: Integer; 
BEGIN 
{determine the type of window--document, modeless, etc. } 














windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 
BEGIN 
BeginUpdate (window) ; 





MyDrawWindow (window) ; 





EndUpdate (window) ; 

END; 

OTHERWISE 

DoUpdateMyDialog (window) ; 
END; {of CASE} 

END; 











The DoUpdate procedure in Listing 2-9 first determines if the window is a document 
window or a modeless dialog box. The MyGetWindowType function is an 
application-defined routine that returns the kMyDocWindow constant if the window is a 
document window and returns other application-defined constants if the window is a 
modeless dialog box. 


If the window is a document window, the procedure does all its drawing of the window 
within calls to the BeginUpdate and EndUpdate procedures. The application-defined 
routine MyDrawWindow performs the actual updating of the document window 

contents. See the chapter “Window Manager” in this book for code that shows the 
MyGetWindowType and MyDrawWindow routines. 


If the window is a modeless dialog box, the code calls the application-defined 
DoUpdat eMyDialog procedure to update the contents of the dialog box. See the chapter 
“Dialog Manager” in this book for details on handling update events in dialog boxes. 


Responding to Activate Events 


When several windows belonging to your application are open, you should allow the 
user to switch from one window to another by clicking in the appropriate window. To 
implement this, whenever your application receives a mouse-down event, you should 
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first determine whether the user clicked in another window by using the Window 
Manager function F indWindow; if so, you can use the Window Manager procedure 
SelectWindow to generate the necessary activate events. 


Before returning to your application and before your application receives any events 
relating to this occurrence, the SelectWindow procedure does some work for you, such 
as removing the highlighting from the window to be deactivated and highlighting the 
newly activated window. At your application’s next request for an event, the Event 
Manager returns an activate event. 


An activate event indicates the window involved and whether the window is being 
activated or deactivated. Your application should perform any other actions needed to 
complete the action of the window becoming active or inactive. For example, when a 
window becomes active, your application should show any scroll bars and restore 
selections as necessary. 


Your application typically receives an activate event (with a flag that indicates the 
window should be deactivated) for the window being deactivated, followed by an 
activate event for the window becoming active. 


Activate events are not placed into the Operating System event queue but are sent 
directly to the Event Manager. 


Figure 2-12 on the next page shows two documents belonging to the same application, 
with Window 1 the active window. When the user clicks in Window 2, your application 
receives a mouse-down event and can use the F indWindow function to determine 
whether the mouse location is in an inactive window. If so, your application should call 
the SelectWindow procedure. The SelectWindow procedure removes highlighting 
of Window 1, highlights Window 2, and generates activate events for both of these 
occurrences. The Event Manager reports the activate events one at a time to your 
application; in this example, the first activate event indicates that Window 1 should be 
deactivated. Your application should hide the scroll bars and remove the highlighting 
from any selections as necessary. 


The next activate event indicates that Window 2 should be activated. Your application 
should show the scroll bars and restore any selections as necessary. If the window needs 
updating as a result of being activated, the Event Manager sends your application an 
update event so that your application can update the window contents. 


Your application also needs to activate or deactivate windows in response to suspend 
and resume events. If you set the accept SuspendResumeEvents flag and the 
doesActivateOnFGSwitch flag in your application’s 'SIZE' resource, your 
application is responsible for activating or deactivating your application’s 

windows in response to handling suspend and resume events. If you set the 

accept SuspendResumeEvents flag and do not set the doesActivateOnFGSwitch 
flag, your application receives an activate event immediately following a suspend or 
resume event. In most cases, you should set both the accept SuspendResumeEvents 
and doesActivateOnFGSwitch flags in your application’s 'SIZE' resource. 
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Figure 2-12 Responding to activate events for a window 
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The what field of an event record for an activate event contains the activateEvt 
constant. The message field contains a pointer to the window being activated or 
deactivated. The modifiers field contains additional information about the activate 
event, along with information about the state of the modifier keys at the time the event 
was posted. Your application can examine bit 0 of the modifiers field of the event 
record to determine if the window should be activated or deactivated. Bit 0 of the 
modifiers field is 1 if the window should be activated and 0 if the window should be 
deactivated. You can use the activeFlag constant to test the state of this bit in the 
modifiers field. 


The when field of the event record contains the number of ticks since the system last 
started up. The where field of the event record contains the location of the cursor at the 
time the activate event occurred. 


Upon receiving an activate event that indicates the window is being deactivated, your 
application should hide any scroll bars and remove the highlighting from any selections 
as necessary. 


Upon receiving an activate event that indicates the window is becoming active, your 
application should show any scroll bars, highlight any selections, and otherwise restore 
the window to the state it was in when it was last active. For example, your application 
should restore the insertion point to its previous position, and the document should be 
scrolled to the position in which the user last left it. Your application should also adjust 
its menus appropriately for the newly active window—adjusting the marks and enabled 
state of menu items based on the state of the active window. 


Listing 2-10 shows an application-defined procedure that responds to activate events. 


Listing 2-10 Responding to activate events 


r 





PROCEDURE DoActivate (window: windowPtr; activate: Boolean; 
event: EventRecord) ; 

VAR 
growRect: Rect; {window's grow rectangle} 
myData: MyDocRecHnd; {window's document record} 
windowType: Integer; 

BEGIN 
{determine the type of window--document, modeless, etc. } 





windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 


HLock (Handle (myData) ); 
WITH myData** DO 
IF activate THEN {window is being activated} 
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BEGIN 





{restore any selections or display caret} 


MyRestoreSelection (window) ; 
{adjust menus as appropriate for this document window} 


MyAdjustMenus; 

{activate any scroll bars} 
vScrollBar*’*’.contrlVis := kControlVisible; 
hScrollBar**.contrlVis := kControlVisible; 


{invalidate area of scroll bars to force update} 
InvalRect (vScrollBar**.contrlRect) ; 

InvalRect (hScrollBar**.contrlRect) ; 

{invalidate area of size box, if any} 





growRect := window*’%.portRect; 

WITH growRect DO 

BEGIN 
top := bottom - kScrollbarAdjust; 
left := right - kScrollbarAdjust; 


END; {end of WITH growRect statement } 
InvalRect (growRect) ; 


END 


ELSE {window is being deactivated} 
BEGIN 
{unhighlight selection (if any) or hide the caret} 
MyHideSelection; 
HideControl (vScrollBar) ; {hide any scroll bars} 
HideControl (hScrollBar) ; 
DrawGrowlcon (window) ; {change size box immediately} 
END; 


HUnLock (Handle (myData) ); 


END; 


{end of kMyDocWindow} 


kMyGlobalChangesID: {this window is a modeless dialog box } 


{ for this app's Global Changes command} 


MyDoActivateGlobalChangesDialog (window, event); 
{handle other modeless dialog boxes as appropriate} 





END; 
END; 





{of CASE} 


Listing 2-10 uses the application-defined function MyGetWindowType to determine 
what type of window is involved with the activate event. If the window is a document 
window, the DoActivate procedure uses the Get WRef£Con function to get a handle 

to the window’s document record. (The DoActivate procedure, and other application- 
defined routines, maintain information about the document associated with a window 
in a document record; the application stores a handle to the document record as the 
window’s reference constant value when it creates a new window. See the chapter 
“Window Manager” in this book for information on defining a document record.) 


Using the Event Manager 


CHAPTER 2 


Event Manager 


If the document window should be activated, the code calls an application-defined 
routine, MyRestoreSelection. Your application should restore any selection or 
display the caret as appropriate. For example, if your application uses TextEdit to 
display text in the content area of windows, you can call the TextEdit procedure 
TEActivate to restore any selection or display a caret at the insertion point. The 
DoActivate procedure then calls another application-defined procedure, 
MyAdjustMenus, to adjust the menus as appropriate for the document window. (See 
the chapter “Menu Manager” for a listing of the MyAdjustMenus procedure.) After 
restoring any selections and adjusting its menus, the code shows the scroll bars and size 
box of the window being activated. It does this by invalidating the area of the scroll bars 
and size box, accumulating these areas into the update region. This causes an update 
event to be generated. The application redraws its controls as appropriate in response to 
update events. 





If the document window should be deactivated, the code in Listing 2-10 unhighlights 
the selection and hides the caret by calling the application-defined procedure 
MyHideSelection. The code then hides the scroll bars and size box of the 
deactivated window. 


If the window associated with the activate event is a modeless dialog box, for example, a 
Global Changes modeless dialog box, the DoActivate procedure calls an 
application-defined procedure to activate or deactivate the dialog box as needed. See the 
“Dialog Manager” chapter in this book for information on handling activate events in 
modeless dialog boxes. 


Responding to Disk-Inserted Events 


When your application uses the Standard File Package to allow the user to choose a file 
to open or choose a location for storing a file, the Standard File Package responds to 
disk-inserted events for your application while interacting with the user. In most cases, if 
your application receives an unexpected disk-inserted event, it can simply check to see if 
the disk was successfully mounted and use the Disk Initialization Manager function 
DIBadMount to notify the user if the disk was not successfully mounted. 


When the user inserts a disk, the Operating System attempts to mount the volume on the 
disk by calling the File Manager function PBMount Vol. If the volume is successfully 
mounted, an icon representing the disk appears on the desktop. The Operating System 
Event Manager then generates a disk-inserted event. If the user is interacting with a 
standard file dialog box, the Standard File Package intercepts the disk-inserted event and 
handles it. Otherwise, the event is left in the event queue for your application to retrieve. 
The Desk Manager also intercepts and handles disk-inserted events if a desk accessory is 
in front. 





Usually your application should handle and not mask out disk-inserted events. The user 
might insert a disk at any time and expects to be warned if the disk is uninitialized or 
damaged. If your application receives a disk-inserted event and the volume was 
successfully mounted, your application usually does not need to take any further action. 
However, if the volume was not successfully mounted, then your application should 
give the user a chance to initialize or eject the uninitialized or damaged disk. 
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If you do mask out disk-inserted events, the event stays in the Operating System event 
queue until your application calls the Standard File Package or until an application that 
does handle disk-inserted events becomes the foreground process. This situation can be 
confusing to the user, so your application should handle disk-inserted events at the time 
that they occur. 


If the volume was successfully mounted and your application either does not use the 
Standard File Package or prompts the user to insert a disk, then you can choose to 
respond to disk-inserted events in whatever way is appropriate for your application. 


The Dialog Manager procedure ModalDialog masks out disk-inserted events. (The 
Standard File Package changes the mask in order to receive disk-inserted events.) If one 
of your application’s modal dialog boxes needs to respond to disk-inserted events, then 
you can change the event mask from within the event filter function that you supply as 
one of the parameters to ModalDialog. Otherwise, your application can respond to the 
disk-inserted event after the user dismisses the modal dialog box. 





The what field of the event record contains the diskEvt constant to indicate a 
disk-inserted event. The message field contains the drive number in the low-order word 
and the result code from the PBMount Vol function in the high-order word. Your 
application can examine the high-order word to determine if the attempt to mount the 
volume was successful. If the volume was not successfully mounted, your application 
can notify the user using the Disk Initialization Manager function DIBadMount. If the 
volume was successfully mounted, your application can use the drive number returned 
in the low-order word for accessing the disk. 


Listing 2-11 shows a procedure that handles disk-inserted events. If the disk was not 
successfully mounted, the procedure notifies the user using the DIBadMount function. 
Otherwise, it does not take any action. See the chapter “Disk Initialization Manager” 
in Inside Macintosh: Files for information on the routines provided by the Disk 
Initialization Manager. 


Listing 2-11 Responding to disk-inserted events 





PROCEDURE DoDiskEvent (event: EventRecord) ; 


























VAR 
thisPoint: Point; 
myErr: OSErnr; 
BEGIN 
IF HiWord(event.message) <> noErr THEN 
BEGIN {attempt to mount was unsuccessful} 
DILoad; {load Disk Initialization Manager} 


SetPt (thisPoint, 120, 120); 
{notify the user} 
myErr := DIBadMount (thisPoint, event.message) ; 
DIUnload; {unload Disk Initialization Manager} 
END 
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ELS! {attempt to mount was successful} 


Gl 








; {record the drive number or do other processing} 
END; 





Responding to Null Events 


When the Event Manager has no other events to report, it returns a null event. The 
WaitNextEvent function reports a null event by returning a function result of FALSE 
and setting the what field of the returned event record to nul lEvt. (The EventAvail 
and GetNextEvent functions also return null events in this manner.) 


When your application receives a null event, it can perform idle processing. Your 
application should do minimum processing in response to a null event, so that other 
processes can use the CPU and so that the foreground process (or your application, if 
it is in the foreground) can respond promptly to the user. 


For example, if your application receives a null event and it is in the foreground, it can 
make the caret blink in the active window. 


If your application receives a null event in the background, it can perform tasks or do 
other processing while in the background. However, your application should not 
perform any tasks that would slow down the responsiveness of the foreground process. 
Your application also should not interact with the user if it is in the background. 


If you don’t want your application to receive null events when it is in the background, 
set the cannotBackground flag in your application’s 'SIZE"' resource. 


Listing 2-12 shows a procedure that performs idle processing in response to a null event. 
If the application is not in the background and the active window is a document 
window, this code calls the TextEdit procedure TEIdle. The TEIdle procedure makes a 
blinking caret appear at the insertion point in the text referred to by the edit record. (This 
application uses TextEdit to display text in its document windows; if you don’t use 
TextEdit for your document windows, provide your own routine to blink the caret.) If 
the active window is a modeless dialog box, the DoIdle procedure calls the Dialog 
Manager function DialogSelect to blink the caret in any editable text item of the 
dialog box. 








Listing 2-12 Handling null events 


PROCEDURE DolIdle (event: EventRecord) ; 


VAR 
window: WindowPtr; 
myData: MyDocRecHnd; 
windowType: Integer; 
itemHit: Integer; 
result: Boolean; 
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BEGIN 


window := FrontWindow; 








{determine the type of window--document, modeless, etc. } 

















windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 
IF (NOT gInBackground) THEN 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
TEIdle (myData**.editRec) ; 
END; 
kMyGlobalChangesID: 
result := DialogSelect (event, window, itemHit); 
END; {of CASE} 
END; 


Handling Operating-System Events 


Operating-system events include suspend, resume, and mouse-moved events. Your 
application receives suspend and resume events as a result of changes in its processing 
status. Your application can request that the Event Manager return mouse-moved events 
whenever the cursor is outside a specified region by specifying a nonempty region in 
the mouseRgn parameter to WaitNextEvent. If you specify an empty region or a NIL 
region handle in the mouseRgn parameter, the Event Manager does not report mouse- 
moved events. 





Your application examines the event record to determine which event it received and to 
obtain additional information associated with the event. 


The what field in the event record of an operating-system event contains the 
osEvt constant. 


The message field in the event record of an operating-system event contains 
information indicating whether the event is a suspend, resume, or mouse-moved event. 
The message field also indicates whether Clipboard conversion is required when the 
application resumes execution. The bits in the message field give this information: 


Bit Contents 
0 0 if a suspend event 
1 if a resume event 
1 0 if Clipboard conversion not required 
1 if Clipboard conversion required 
2-23 Reserved 


24-31 suspendResumeMessage if a suspend or resume event 
mouseMovedMessage if a mouse-moved event 
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Note that you need to examine bits 24-31 of the message field to determine what kind 
of operating-system event you have received. Bits 24-31 in the message field contain 
one of these two constants: 


CONST suspendResumeMessage = $01; {suspend or resume event} 





mouseMovedMessage = SFA; {mouse-moved event } 





If the event is a suspend or resume event, you need to examine bit 0 to determine 
whether that event is a suspend or resume event. Bits 0 and 1 are meaningful only if bits 
24-31 indicate that the event is a suspend or resume event. You can use the resumeF lag 
constant to determine whether the event is a suspend or resume event. If the event is a 
resume event, you can use the convertClipboardFlag constant to determine whether 
Clipboard conversion from the Clipboard to your application’s scrap is required: 


CONST resumeFlag 
convertClipboardFlag = 2; {Clipboard conversion required} 


41. {resume event } 


Whenever the user performs a copy or cut operation, your application should copy the 
selected data either to its private scrap or, if your application doesn’t have a private 
scrap, to the Clipboard. If your application uses a private scrap, you need to convert the 
data from your private scrap to the Clipboard whenever your application receives a 
suspend event. Likewise, you need to convert any data from the Clipboard (if it has 
changed) when your application receives a resume event. For resume events, the value 
of bit 1 of the message field is 1 if your application needs to read in the new contents of 
the Clipboard. 


Listing 2-13 shows a procedure that responds to operating-system events. 


Listing 2-13 Responding to operating-system events 





PROCEDURE DoOSEvent (event: EventRecord) ; 























CASE BAnd(BRotL(event.message, 8), SFF) OF {get high byte} 
mouseMovedMessage: 











DoIdle(event); {mouse-moved same as idle for this app} 





suspendResumeMessage: 











DoSuspendResumeEvent (event); {handle supend/resume event} 
END; 
END; 





The DoOSEvent procedure in Listing 2-13 is called from the DoEvent procedure (shown 
in Listing 2-3 on page 2-26) whenever the application receives an operating-system 
event. The DoOSEvent procedure examines the high byte of the message field to 
determine whether the event is a mouse-moved, suspend, or resume event, and it then 
calls an application-defined procedure to handle the event. Note that most applications 
either adjust the cursor in response to mouse-moved events or adjust the cursor in their 
event loop whenever any type of event is received. The code in this chapter uses the 
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latter approach, and thus the DoOSEvent procedure simply calls its DoIdle procedure 
in response to mouse-moved events. The next two sections show the code that handles 
suspend, resume, and mouse-moved events. 





Responding to Suspend and Resume Events 





The WaitNextEvent function returns a suspend event when your application is about 
to be switched to the background. WaitNextEvent returns a resume event when your 
application becomes the foreground process again. 


Upon receiving a suspend event, your application should deactivate the front window, 
remove the highlighting from any selections, and hide any floating windows. Your 
application should also convert any private scrap into the global scrap, if necessary. 

If your application shows a window that displays the Clipboard contents, you should 
hide this window also, as the user might change the contents of the Clipboard before 
returning to your application. Your application can also do anything else necessary to 
get ready for a major switch. Then your application should call WaitNextEvent to 
relinquish the processor and allow the Operating System to schedule other processes 
for execution. 





Upon receiving a resume event, your application should activate the front window and 
restore any windows to the state the user left them in at the time of the previous suspend 
event. For example, your application should show scroll bars, restore any selections that 
were previously in effect, and show any floating windows. Your application should copy 
the contents of the Clipboard and convert the data back to its private scrap, if necessary. 
If your application shows a window that displays the Clipboard contents, you can 
update the contents of the window after reading in the scrap. Your application can then 
resume interacting with the user. 


Responding to a suspend or resume event usually involves activating or deactivating 
windows. If you set the accept SuspendResumeEvents flag and the 
doesActivateOnFGSwitcnh flag in your application’s 'SIZE" resource, your 
application is responsible for activating or deactivating your application’s windows 
in response to handling suspend and resume events. 





Note 

If you set the accept SuspendResumeEvents flag and do not set the 
doesActivateOnFGSwitcnh flag in your application’s 'SIZE' 
resource, your application receives an activate event immediately 
following a suspend or resume event. In most cases, you should set both 
the accept SuspendResumeEvents and doesActivateOnFGSwitch 
flags in your application’s 'SIZE" resource. @ 





Your application can use the Scrap Manager functions InfoScrap, ZeroScrap, 
Put Scrap, and Get Scrap to read data from and write data to the Clipboard. 
See the chapter “Scrap Manager” in Inside Macintosh: More Macintosh Toolbox for 
additional details. 
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Note 

If your application does not handle suspend and resume events (as 
indicated by a flag in its 'SIZE' resource), then the Operating System 
has to trick your application into performing scrap coercion to ensure 
that the contents of the Clipboard can be transferred from one applica- 
tion to another. This process adds to the time it takes to move the 
foreground application to the background and vice versa. 





Listing 2-14 shows a procedure that responds to suspend and resume events. The 
DoSuspendResumeEvent procedure first gets a pointer to the front window using 
the Window Manager function FrontWindow. It then examines bit 0 of the message 


field of the event record to determine whether the event is a suspend or resume event. 


If the event is a resume event, the code examines bit 1 of the message field of the 

event record to determine whether it needs to read in the contents of the scrap. If so, 
the code calls an application-defined routine, MyConvert Scrap, that reads in the 
scrap and converts the contents to its private scrap. It then sets a private global flag, 


gInBackground, to FALSE, to indicate that the application is not in the background. It 
then calls another application-defined routine, DoAct ivate (shown in Listing 2-10), to 





activate the application’s front window. 


For suspend events, the DoSuspendResumeEvent procedure calls the 
application-defined MyConvert Scrap procedure to copy the contents of its private 
scrap to the global scrap. It then sets a private global flag, gInBackground, to TRUI 
indicate that the application is in the background. Finally, it calls another 
application-defined routine to deactivate the application’s front window. 








Listing 2-14 Responding to suspend and resume events 





PROCEDURE DoSuspendResumeEvent (event: EventRecord) ; 
VAR 
currentFrontWindow: WindowPtr; 











BEGIN {handle suspend/resume event} 





currentFrontWindow := FrontWindow; 








IF (BAnd(event.message, resumeFlag) <> 0) THEN 





BEGIN {it's a resume event} 
IF (BAnd(event.message, convertClipboardFlag) <> 0) THEN 





MyConvertScrap (kClipboardToPrivate) ; 
gInBackground := FALSE; 
{activate front window} 

DoActivate (currentFrontWindow, NOT gInBackground, event); 
MyShowClipboardWindow; {show Clipboard window if it was 
{ showing at last suspend event} 
MyShowFloatingWindows; {show any floating windows} 

END 
ELSE 
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BEGIN {it's a suspend event} 
MyConvertScrap (kPrivateToClipboard) ; 





gInBackground := TRUE; 


{deactivate front window} 





DoActivate(currentFrontWindow, NOT gInBackground, event); 
MyHideClipboardWindow; {hide Clipboard window if showing} 
MyHideFloatingWindows; {hide any floating windows} 
END; 
END; 





Your application can receive processing time while in the background and perform tasks 
in the background, but your application should not interact with the user or perform 
tasks that would slow down the responsiveness of the foreground process. 


If you need to notify the user of some special occurrence while your application is 
executing in the background, you should use the Notification Manager to queue a 
notification request. See the chapter “Notification Manager” in Inside Macintosh: 
Processes for examples of how to post notification requests. 


Responding to Mouse-Moved Events 


Whenever the user moves the mouse, the mouse driver, the Event Manager, and your 
application are responsible for providing feedback to the user. The mouse driver 
performs low-level functions, such as continually polling the mouse for its location and 
status and maintaining the current location of the mouse in a global variable. 


As the user moves the mouse, the user expects the cursor to move to a corresponding 
relative location on the screen. The low-level interrupt routines of the mouse driver map 
the movement of the mouse to relative locations on the screen. Whenever the user moves 
the mouse, a low-level interrupt routine of the mouse driver moves the cursor displayed 
on the screen and aligns the hot spot of the cursor with the new mouse location. A hot 
spot is a point that the mouse driver uses to align the cursor with the mouse location. 


Your application is responsible for setting the initial appearance of the cursor, for 
restoring the cursor after WaitNextEvent returns, and for changing the appearance of 
the cursor as appropriate for your application. For example, most applications set the 
cursor to the I-beam when the cursor is inside a text-editing area of a document, and 
change the cursor to an arrow when the cursor is inside the scroll bar of a document. 
Your application can achieve this effect by requesting that the Event Manager report 
mouse-moved events if the user moves the cursor out of a region you specify in the 
mouseRgn parameter to the WaitNextEvent function. 








The mouse driver and your application control the shape and appearance of the cursor. 
A cursor can be any 256-bit image, defined by a 16-by-16 bit square. The mouse driver 
displays the current cursor, which your application can change by using various cursor- 
handling routines (for example, the Set Cursor procedure). 


Figure 2-13 shows the standard arrow cursor. You can initialize the cursor to the 
standard arrow cursor using the InitCursor procedure. In Figure 2-13, the hot spot 
for the arrow cursor is at location (1,1). See Inside Macintosh: Imaging for information on 
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the cursor-handling routines and for specific details of how your application can define 
its Own cursors. 


Figure 2-13 The standard arrow cursor 





Figure 2-14 shows four other common cursors that are available to your application: the 
I-beam, crosshairs, plus sign, and wristwatch cursors. 


Figure 2-14 The |I-beam, crosshairs, plus sign, and wristwatch cursors 
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The I-beam, crosshairs, plus sign, and wristwatch cursors are defined as resources, 
and your application can get a handle to any of these cursors by specifying their 
corresponding resource IDs to the Get Cursor function. These constants specify the 
resource IDs for the I-beam, crosshairs, plus sign, and wristwatch cursors: 





CONST iBeamCursor = 1;{used in text editing} 
crossCursor = 2;{often used for manipulating graphics} 
plusCursor 


3; {often used for selecting fields in } 
{ an array} 

watchCursor = 4;{used to mean a lengthy operation } 

{ is in progress} 
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You can change the appearance of the cursor using the Set Cursor procedure or other 
cursor-handling routines. You can also define your own cursors, store them in resources, 
and use them as needed in your application. 


Your application usually needs to change the shape of the cursor as the user moves the 
cursor to different areas within a document. Your application can use mouse-moved 
events to accomplish this. Your application also needs to adjust the cursor in response to 
resume events. Most applications adjust the cursor once through the event loop in 
response to almost all events. 


You can request that the Event Manager report mouse-moved events whenever 

the cursor is outside of a specified region that you pass as a parameter to the 
WaitNextEvent function. If you specify an empty region or a NIL handle to 

the WaitNextEvent function, WaitNextEvent does not report mouse-moved events. 














If you specify a nonempty region in the mouseRgn parameter to the WaitNextEvent 
function, WaitNextEvent returns a mouse-moved event whenever the cursor is out of 
this region. For example, Figure 2-15 shows a document window. An application might 
define two regions: a region that encloses the text area of a window (the I-beam region), 
and a region that defines the scroll bars and all other areas outside the text area (the 
arrow region). By specifying the I-beam region to WaitNextEvent, the mouse driver 
continues to display the I-beam cursor until the user moves the cursor out of this region. 








Figure 2-15 The arrow region and the I-beam region 
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When the user moves the cursor out of the I-beam region, WaitNextEvent reports a 
mouse-moved event. Your application can then change the I-beam cursor to the arrow 
cursor and change the mouseRgn parameter to the area defined by the scroll bars and 
all other areas outside of the I-beam region. The cursor now remains an arrow until the 
user moves the cursor out of this region, at which point your application receives a 
mouse-moved event. 


Figure 2-16 shows how an application might change the cursor from the I-beam cursor to 
the arrow cursor after receiving a mouse-moved event. 
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Figure 2-16 Changing the cursor from the I-beam cursor to the arrow cursor 
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Note that your application should recalculate the mouseRgn parameter when it receives 
a mouse-moved event; otherwise, it will continue to receive mouse-moved events as 
long as the cursor position is outside the original region. 





After receiving any event other than a high-level event, the MyEvent Loop procedure 
(shown in Listing 2-2 on page 2-24) calls the application-defined procedure 
MyAdjustCursor to adjust the cursor. After adjusting the cursor, if the event is an 
operating-system event, the DoEvent procedure calls the DoOSEvent procedure. The 
DoOSEvent procedure calls the DoIdle procedure for mouse-moved events. The 
DoIdle procedure simply calls TEId1e to blink the caret in the text-editing window. 














Listing 2-15 shows the application-defined routine MyAdjustCursor. 


Listing 2-15 Changing the cursor 








PROCEDURE MyAdjustCursor (mouse: Point; VAR region: RgnHandle); 
VAR 























window: WindowPtr; 
arrowRgn: RgnHandle; 
iBeamRgn: RgnHandle; 
iBeamRect: Rect; 
myData: MyDocRecHnd; 
windowType: Integer; 

BEGIN 

window := FrontWindow; 


{determine the type of window--document, modeless, etc. } 





windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 
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BEGIN 


{initialize regions for arrow and I-beam} 
arrowRgn := NewRgn; 
ibeamRgn := NewRgn; 


{set arrow region to large region at first} 
SetRectRgn(arrowRgn, -32768, -32768, 32766, 32766); 


{calculate I-beam region} 
{first get the document's TextEdit view rectangle} 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
iBeamRect := myData**.editRec**%.viewRect; 
SetPort (window) ; 
WITH iBeamRect DO 
BEGIN 

LocalToGlobal (topLeft) ; 

LocalToGlobal (botRight) ; 
END; 
RectRgn(iBeamRgn, iBeamRect) ; 
WITH window’.portBits.bounds DO 

SetOrigin(-left, -top); 
{intersect I-beam region with window's visible region} 
SectRgn(iBeamRgn, window*.visRgn, iBeamRgn) ; 
SetOrigin(0,0); 


{calculate arrow region by subtracting I-beam region} 
DiffRgn(arrowRgn, iBeamRgn, arrowRgn) ; 


{change the cursor and region parameter as necessary} 
IF PtInRgn (mouse, iBeamRgn) THEN {cursor is in I-beam rgn} 
BEGIN 
SetCursor (GetCursor (iBeamCursor) *%); {set to I-beam} 
CopyRgn(iBeamRgn, region); {update the region param} 
END; 


{update cursor if in arrow region} 
IF PtInRgn (mouse, arrowRgn) THEN {cursor is in arrow rgn} 
BEGIN 
SetCursor (arrow) ; {set cursor to the arrow} 
CopyRgn(arrowRgn, region); {update the region param} 
END; 
DisposeRgn (iBeamRgn) ; 
DisposeRgn (arrowRgn) ; 


END; {of kMyDocWindow} 
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kMyGlobalChangesID: 
MyCalcCursorRgnForModelessDialogBox (window, region) ; 


kNil: 
BEGIN 
MySetRegionNoWindows (kNil, region); 








SetCursor (arrow) ; 
END; 
END; {of CASE} 
END; 











The MyAdjustCursor procedure sets the cursor appropriately, according to whether a 
document window or modeless dialog box is active. 


For a document window, the code in Listing 2-15 defines two regions, specified by 

the arrowRgn and iBeamRgn variables. If the cursor is inside the region described 
by the arrowRgn variable, the code sets the cursor to the arrow cursor and returns the 
region described by arrowRgn. Similarly, if the cursor is inside the region described 
by the iBeamRgn variable, the code sets the cursor to the I-beam cursor and returns 
the region described by iBeamRgn. 





The MyAdjustCursor procedure calculates the two regions by first setting the arrow 
region to the largest possible region. It then sets the I-beam region to the region 
described by the document’s TextEdit view rectangle. This region typically corresponds 
to the content area of the window minus the scroll bars. (If your application doesn’t 

use TextEdit for its document window, then set this region as appropriate to your 
application.) The code then adjusts the I-beam region so that it includes only the part of 
the content area that is in the window’s visible region (for example, to take into account 
any floating windows that might be over the window). The code then sets the arrow 
region to include the entire screen except for the region occupied by the I-beam region. 


The procedure then determines which region the cursor is in and sets the cursor and 
region parameter appropriately. 


For modeless dialog boxes (for example, the Global Changes modeless dialog box), the 
MyAdjustCursor procedure calls an application-defined routine to appropriately 
adjust the cursor for the modeless dialog box. The MyAdjustCursor procedure also 
appropriately adjusts the cursor if no windows are currently open. 


Handling High-Level Events 


High-level events provide a means of communication between applications. Apple 
events are high-level events that follow the Apple Event Interprocess Messaging Protocol 
(AEIMP). In most cases, you should use Apple events rather than define your own 
high-level events if you wish to communicate with other applications. If you plan to use 
Apple events, see Inside Macintosh: Interapplication Communication for specific information 
on Apple events, and refer to this section for specific details about how the Event 
Manager reports high-level events. 
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To receive high-level events, you must set the appropriate flags in your application’s 
'SIZE' resource. You must set the isHighLevelEventAware flag if your application 
is to receive any high-level events. You must set the localAndRemoteHLEvents 

flag for your application to receive high-level events sent from another computer on 

the network. In addition, to receive high-level events from another computer, your 
application must be shared and Program Linking must be enabled. The user shares your 
application by selecting your application in the Finder and choosing Sharing from the 
File menu and enables Program Linking from the Sharing Setup control panel. 














If you set the isHighLevelEventAware flag in your application’s 'SIZE"' resource, 
your application receives the Finder information in the form of Apple events. The Finder 
information is the information your application can use to determine which files to open 
or print. Your application must respond to the required Apple events (Open Application, 
Open Documents, Print Documents, and Quit Application) that are sent by the Finder if 
your application sends or receives high-level events. 





The what field in the event record of a high-level event contains the kHighLevelEvent 
constant. 


To determine the type of high-level event received, your application needs to examine 
the message and where fields of the event record. For high-level events, these two 
fields of the event record have special meanings. 


The message field and the where field of the event record together define the specific 
type of high-level event received. Your application should interpret these fields as 
having the data type OSType, not LongInt or Point. 


The message field contains the event class of the high-level event. For example, Apple 
events sent by the Edition Manager have the event class 'sect'. Youcan define your own 
group of events that are specific to your application. If you have registered your 
application signature with Apple Computer, Inc., then you can use your signature to 
define the class of events that belong to your application. Note, however, that Apple 
reserves the use of all event classes whose names contain only lowercase letters and 
nonalphabetic characters. 


For high-level events, the where field in the event record contains a second message 
specifier, called the event ID. The event ID defines the particular type of event (or 
message) within the class of events defined by the event class. For example, the Section 
Read event sent by the Edition Manager has event class 'sect' and event ID 'read’. The 
Open Documents event sent by the Finder has event class 'aevt' and event ID 'odoc'. 
You can define your own set of event IDs corresponding to your own event class. For 
example, if the message field contains 'biff' and the where field contains 'cmd1', then 
the high-level event indicates the type of event defined by 'cmd1' within the class of 
events defined by the application with the signature 'biff'. 


Note 


If your application supports Apple events, you can call the 
AEProcessAppleEvent function to determine the type of Apple event 
received, rather than examining the message andwhere fields. ¢@ 
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Note that because the where field of an event record for a high-level event is used to 
select a specific kind of event (within the class determined by the message field), 
high-level event records do not contain the mouse location at the time of the event. You 
should not interpret the where field before interpreting the what field because different 
event classes can contain overlapping sets of event IDs. 


Unlike low-level events and operating-system events, high-level events may not be 
completely determined by the event record returned to your application when it calls 
WaitNextEvent. For example, you might still need to know which other application 
sent you the high-level event or what additional data that application wants to send you. 
Your application can obtain this further information about the high-level event by calling 
the AcceptHighLevelEvent function. The additional information associated with a 
high-level event includes 


m the identity of the sender of the event 


m™ aunique number that identifies the request associated with the event or associates the 
particular event with a request from a previous event 





m the address and length of a data buffer that can contain optional data 


To obtain this additional information, your application must call 
AcceptHighLevelEvent before calling WaitNextEvent again. By convention, 
calling AcceptHighLevelEvent indicates that your application intends to process 
the high-level event. 








To accept an Apple event, call the AEProcessAppleEvent function instead of 

the AcceptHighLevelEvent function. The Apple Event Manager also extracts 
any additional information associated with the Apple event at your application’s 
request. This chapter discusses how to accept high-level events using the 
AcceptHighLevelEvent function; for information on the AEProcessAppleEvent 
function, see Inside Macintosh: Interapplication Communication. 











Responding to Events From Other Applications 


You can identify high-level events by the value in the what field of the event record. The 
messageand where fields further classify the type of high-level event. Your application 
can choose to recognize as many events as are appropriate. Some high-level events may 
be fully specified by their event record only, while others may include additional 
information in an optional buffer. To get that additional information or to find the sender 
of the event, use the AcceptHighLevelEvent function. 





Note 
To respond to an Apple event, use the Apple Event Manager, as 
described in Inside Macintosh: Interapplication Communication. 


Listing 2-16 on the next page illustrates how to respond to a high-level event. 





The DoHighLevelEvent procedure in Listing 2-16 first determines the type of high- 
level event received by checking the message and where fields of the event record. It 
then uses AcceptHighLevelEvent to get any additional data associated with the 
event. This particular application recognizes only one type of high-level event. If the 
event is not of this type, the code assumes that the event is an Apple event and calls 
AEProcessAppleEvent to handle the event. 


Using the Event Manager 2-69 


2-70 


CHAPTER 2 


Event Manager 


In general, you cannot know in advance how big the optional data buffer is, so you can 
allocate a zero-length buffer and then resize it if the call to AcceptHighLevelEvent 
returns the bufferIsSmall1 result code. 


Listing 2-16 Accepting a high-level event 





PROCEDURE DoHighLevelEvent (event: EventRecord) ; 
VAR 
myTarg: TargetID; {target ID record} 





myRefCon: LongInt; 
myBuff: Ptr; 
myLen: LongInt; 





myErr: OSErr; 
BEGIN 
IF (event.message = LongInt (kMySpecialHLEventClass)) AND 
(LongInt (event.where) = LongInt (kMySpecialHLEventID)) THEN 
BEGIN 
{it's a high-level event that doesn't use AEIMP} 
myLen := 0; {start with a O-byte buffer} 
myBuff := NIL; 
myErr:=AcceptHighLevelEvent (myTarg,myRefCon, myBuff, myLen); 
IF myErr = bufferIsSmall THEN 
BEGIN 
myBuff := NewPtr(myLen); {allocate needed storage} 














myErr := AcceptHighLevelEvent (myTarg, myRefCon, myBuff, 
myLen) ; 
IF myErr = nokrr THEN 
; {perform any action requested by the event} 
END; 
IF myErr <> noErr THEN 




















DoError (myErr); {perform the necessary error handling} 
END 
ELSE 
BEGIN {otherwise, assume that the event is an Apple event} 








myErr := AEProcessAppleEvent (event) ; 
IF myErr <> noErr THEN 














DoError (myErr); {perform the necessary error handling} 
END; 
END; 


The AcceptHighLevelEvent function returns additional information and data 
associated with the event. The ID of the sender of the event is returned in the first 
parameter, which is a target ID record. You can inspect the fields of that record to 
determine which application sent the event. The target ID record contains the session 
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reference number that identifies the connection with the other application as well as the 
port name and location name of the sender. If the high-level event requires that you 
return information, you can use the information returned in the target ID record to 
send an event back to the requesting application. See “Determining the Sender of a 
High-Level Event” on page 2-72 and “Sending High-Level Events” on page 2-73 for 
specific information on the target ID record. 





The second parameter to Accept HighLevelEvent, the reference constant parameter, is 
a unique number that identifies the request associated with the event or identifies that 
the particular event is related to a request from a previous event. If you send a response 
to this event, you should use the same value for the reference constant so that the sender 
of the event can associate the reply with the original request. 


The third parameter points to any additional data associated with the event. Any data 
in this additional buffer is defined by the particular high-level event. On input, the 
fourth parameter to AcceptHighLevelEvent, the length parameter, contains the 
size of the buffer. If no error occurs, on output the length parameter contains the size 
of the message accepted. If the AcceptHighLevelEvent function returns the result 
code buf ferIsSmal1, the length parameter contains the size of the message yet to 
be received. 





Searching for a Specific High-Level Event 


Sometimes you do not want to accept the next available high-level event pending for 
your application. Instead, you might want to select one event from among all the 
high-level events in your application’s high-level event queue. For example, you might 
want to look for a return receipt for a high-level event you previously posted before 
processing other high-level events. 





You can select a specific high-level event by calling the Get SpecificHighLevelEvent 
function. One of the parameters you pass to this function is a filter function that you 
provide. Your filter function should examine an event in your application’s high-level 
event queue and determine whether it is the kind of event you wish to receive. If it is, 
your filter function returns TRUE. This indicates that your filter function does not want 
to inspect any more events. If the filter function finds an event of the desired type, it 
should call AcceptHighLevelEvent to retrieve the event. When your function returns 
TRUE, the Get SpecificHighLevelEvent function itself returns TRUE. 








If your filter function returns FALSE for an event in the high-level event queue, then 
Get SpecificHighLevelEvent looks at the next event in the high-level event queue 
and executes your filter function. If the filter function returns FALSE for all the high- 
level events in the queue, then Get SpecificHighLevelEvent itself returns FALSE to 
your application. 





Here’s how you declare the filter function whose address you pass to the 
Get SpecificHighLevelEvent function: 





FUNCTION MyFilter (yourDataPtr: Ptr; 
msgBuff: HighLevelEventMsgPtr; 
sender: TargetID): Boolean; 
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When your application calls Get SpecificHighLevelEvent, you pass it a parameter 
that indicates the criteria your filter function should use to search for a specific event. 
The Get SpecificHighLevelEvent function passes this information to your filter 
function in the yourDataPtr parameter. The Get SpecificHighLevelEvent 
function also provides your filter function with information about the event record of the 
high-level event in the msgBuff parameter as well as information about the sender of 
the high-level event in the sender parameter. 











The msgBuff parameter contains a pointer to a high-level event message record that has 
this structure: 





TYPE HighLevelEventMsg = 











RECORD 
HighLevelEventMsgHeaderLength: Integer; 
version: Integer; 
reservedl: LongInt; 
theMsgEvent: EventRecord; 
userRefCon: LongInt; 
postingOptions: LongIint; 
msgLength: LongInt; 

END; 


HighLevelEventMsgPtr= *“HighLevelEventMsg; 


When you call Get SpecificHighLevelEvent and it executes your filter function for 
a high-level event waiting in the high-level event queue, the fields of the high-level event 
message record are filled in by the Event Manager. You can then compare the fields of 
this record to the information in the yourDataPtr parameter to determine whether that 
event suits your needs. For example, the yourDataPtr parameter might contain the 
signature of a return receipt. You can test its value against the event class of the event 
record contained in the theMsgEvent field of the high-level event message record. 





Determining the Sender of a High-Level Event 


When you receive a high-level event, part of the information returned by 
AcceptHighLevelEvent is the identity of the sender of the event. You can use that 
information to respond selectively to requests made by other applications or to find 
which application to send any replies to. The information about the sender is provided 
in the form of a target ID record, defined as follows: 


TYPE TargetID = 





RECORD 
sessionID: LongInt; {session reference number} 
name: PPCPortRec; {sender's port name} 
location: LocationNameRec; {sender's location name} 
recvrName: PPCPortRec; {reserved} 

END; 
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The sessionID field corresponds to the session reference number created by the PPC 
Toolbox. This is a 32-bit number that uniquely identifies a PPC Toolbox session (or 
connection) with another application. The name and location fields contain the 
sender’s port name and location name. If the sending application is on the same 
computer as the receiving application, you can determine the sending application’s 
process serial number by calling the GetProcessSerialNumberFromPortName 
function. 


Sending High-Level Events 


You use the Post HighLevelEvent function to send a high-level event to another 
application. When doing so, you need to provide six pieces of information: 


m an event record with the event class and event ID assigned appropriately 
m the identity of the recipient of the event 


m™ a unique number that identifies the communication associated with this 
particular event 


m a data buffer that can contain optional data 
m the length of the data buffer 


m options determining how the event is posted 


Note 

To send an Apple event, use the Apple Event Manager function 
AESend. The Apple Event Manager uses the Event Manager to post 
Apple events. For information on posting Apple events, see Inside 
Macintosh: Interapplication Communication. 


When you post a high-level event to an application on the same computer, you can 
specify its recipient in one of four ways: 


m by port name and location name (specified in a target ID record) 
m by asession reference number 

a by the application’s creator signature 

m by a process serial number 


To specify the recipient of a high-level event sent across a network, you can use only 

the receiving application’s port name and location name or its session reference number. 
You can use any of the four ways when sending high-level events to applications on the 
local computer. 


You specify the recipient of a high-level event in the receiverID parameter when you 
use the PostHighLevelEvent function. To specify a port name and location name, 
provide the address of a target ID record in the receiverID parameter. To specify a 
process serial number, provide its address in the receiverID parameter. To specify a 
session reference number, or signature, provide the data in the receiverID parameter. 


When you are replying to a high-level event, it is easy to identify the recipient because 
you can use the target ID record that you receive from AcceptHighLevelEvent, the 
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session reference number contained in that target ID record, or the process serial number 
(if the receiving process is local). Note that replying by session reference number is 
always the fastest way to respond to a high-level event. 


When you are not replying to a previous event, you need to determine the identity of 
the target application yourself. You can use one of several methods to do this. If the 
target application is on the local computer, you can search for that application’s creator 
signature or its process serial number by calling the Get ProcessInformation 
function. See the chapter “Process Manager” in Inside Macintosh: Processes for a detailed 
explanation of the Get ProcessInformation function and for examples of how to use 
it to generate a list of process serial numbers of all open processes on the local computer. 


If the application to which you want to send a high-level event is located on a remote 
computer, you need to identify it either by its session reference number or by its port 
name and location name. You can call the PPCBrowser function to let the user browse 
for a specific port. You can call the IPCListPorts function to obtain a list of all ports 
registered with the target PPC Toolbox. See the chapter “Program-to-Program 
Communications Toolbox” in Inside Macintosh: Interapplication Communication for an 
explanation of both of these functions. 


As just described, you can identify the recipient of the high-level event in one of four 
ways. Listing 2-17 illustrates how to send a high-level event to an application on the 
local computer using the application’s creator signature. In this example, an application 
is sending a high-level event to the application with the creator signature of 'boff'. 
The specific high-level event being sent is identified by the event class 'boff' and the 
event ID 'cmd1'. 


Listing 2-17 Posting a high-level event by application signature 


PROCEDURE MyPostTest; 


VAR 
myEvent: EventRecord; {an event record} 
myRecvID: OSType; {receiver ID} 
myOpts: LongIint; {posting options} 
myErr: OSErr; 
BEGIN 
myEvent.what := kHighLevelEvent; 
myEvent.message := LongInt('boff'); {event class} 
myEvent.where := Point (LongInt ('cmdl"')); {event ID} 


{the receiver is identified by its signature and } 
{ a return receipt is requested} 


myOpts := receiverIDisSignature + nReturnReceipt; 

myRecvID := 'boff'; {receiver's signature} 

myErr := PostHighLevelEvent (myEvent, Ptr(myRecvID), 0, NIL, 0, 
myOpts) ; 


IF myErr <> noErr THEN 
DoError (myErr) ; 
END; 
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In this example of using the Post HighLevelEvent function, there is no additional data 
to transmit, so the sending application provides NIL as the pointer to the data buffer and 
sets the buffer length to 0. The myOpts variable specifies posting options. 


Posting options are of two types: delivery options and options associated with the 
receiverID parameter. You can specify one or more delivery options to indicate if you 
want the other application to receive the event at the next opportunity and to indicate if 
you want acknowledgment that the other application received the event. You use the 
options associated with the receiverID parameter to indicate how you are specifying 
the recipient of the event. To set the various posting options, use these constants: 





CONST nAttnMsg = $00000001;{give this message priority} 
nReturnReceipt = $00000200; {return receipt requested} 
receiverIDisTargetID = $00005000;{ID is port name and location name} 
receiverIDisSessionID = $00006000;{ID is PPC session ref number} 
receiverIDisSignature = $00007000;{ID is creator signature} 
receiverIDisPSN = $00008000;{ID is process serial number} 


When you specify the receiving application in the receiverID parameter, you can use 
these constants to specify the receiver of the event by port name and location name, 
session reference number, process serial number, or signature. Any of these specifications 
allows you to send an event to another application on the local computer. For example, 
in Listing 2-17 the myOpts variable indicates that the receiver is identified by its creator 
signature, and the myRecvID variable contains the receiver’s creator signature. To send 
events to an application on a remote computer, you can specify the recipient only by the 
session reference number or by the port name and location name. 


When you specify the receiver of the event by port name and location name, use the 
receiverIDisTargetID constant in the posting options parameter and specify the 
address of a target ID record in the receiverID parameter. 


TYPE TargetID = 





RECORD 
sessionID: LongInt; {unused for posting} 
name: PPCPortRec; {recipient's port name} 
location: LocationNameRec; {recipient's port loc} 
recvrName: PPCPortRec; {unused for posting} 
END; 


When you pass a target ID record, you need to specify only the name and location 
fields. You can use the IPCListPorts function to list all of the existing port names 
along with information on whether the port will accept authenticated service on the 
computer specified by the location name. For information on how to use the 
IPCListPorts function, see the chapter “Program-to-Program Communications 
Toolbox” in Inside Macintosh: Interapplication Communication. 


You can also use the PPCBrowser function to fill in a target ID record. Listing 2-18 on 
the next page illustrates how to use the PPCBrowser function to post a high-level event. 
In this example, the sending application wants to locate a dictionary application and 
have the dictionary return the definition of a word to it. 
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Listing 2-18 Using the PPCBrowser function to post a high-level event 





FUNCTION MyPostWithPPCBrowser (aTextPtr: Ptr; textlength: LongInt): OSErr; 


VAR 


myHLEvent: EventRecord; 


myErr: OSErnr; 


myNumTries: Integer; 


myPortInfo: PortInfoRec; 


myTarget: TargetID; 


BEGIN 


{use PPCBrowser to get the target} 
myErr := PPCBrowser('Select an Application', 'Application', FALSE, 


IF 


myTarget.location, myPortInfo, NIL, ''); 
myErr = NoErr THEN 





BEGIN 





{copy port name into myTarget.name} 
myTarget.name := myPortInfo.name; 


myHLEvent.what := kHighLevelEvent; 





myHLEvent.message := LongInt('Dict'); 
myHLEvent.where := Point (LongInt('Defn')); 


{if a connection is broken, then sessClosedErr is returned to } 
{ PostHighLevelEvent; to reestablish the connection, just post } 


{ the event one more time} 





myNumTries := 0; 
REPEAT 
myErr := PostHighLevelEvent (myHLEvent, @myTarget, 0, aTextPtr, 
textlength, receiverIDisTargetID) ; 
myNumTries := myNumTries + 1; 


UNTIL (myErr <> sessClosedErr) OR (myNumTries > 1); 


END; 
MyPostWithPPCBrowser := myErr; {return any error} 


END; 
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The application-defined function in Listing 2-18 uses the PPCBrowser function to 
display a dialog box asking the user to select a dictionary. (For additional information 

on the PPCBrowser function, see Inside Macintosh: Interapplication Communication.) If 
the user selects a dictionary, this code posts a high-level event to that dictionary 
application asking for the definition of the selected text. Note that the sending 
application and the receiving application must both agree that definition queries are to 
be of event class 'Dict' and event ID 'Defn’. It is necessary to define a private protocol 
only in cases in which no suitable Apple event exists. 
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Note 

You should avoid passing handles to the receiving application in an 
attempt to share a block of data. It is better to put the relevant data into a 
buffer (as illustrated in Listing 2-18) and pass the address of the buffer. If 
you absolutely must share data by passing a handle, make sure that the 
block of data is located in the system heap. 


If a high-level event is posted successfully, PostHighLevelEvent returns the result 
code noErr, which indicates only that the event was successfully passed to the PPC 
Toolbox. Your application needs to call another Event Manager routine (EventAvail, 
GetNextEvent, or WaitNextEvent) to give the other application an opportunity to 
receive the event. 


The event you send might require the other application to return some information to 
your application by sending a high-level event back to your application. You can scan for 
the response by using Get SpecificHighLevelEvent. If your application must wait 
for this event, you might want to display a wristwatch cursor or take other action as 
appropriate to your application. You also might want to implement a timeout 
mechanism in case your application never receives a response to the event. 


Requesting Return Receipts 


When you post a high-level event, you can request a return receipt by including the 
nReturnReceipt constant as one of the posting options. This requests that the Event 
Manager send your application a high-level event that tells you whether the other 
application accepted your event. Note that this does not necessarily mean that the other 
application performed any action you might have requested from it. 


A return receipt is a high-level event having an event class and an event ID indicated by 
these two constants: 


CONST HighLevelEventMsgClass = 'Jjaym'; 


rtrnReceiptMsgID = 'rtrn'; 


Return receipts are posted by the Event Manager on the computer of the receiving 
application (and not by the receiving application itself). No data buffer is associated with 
a return receipt. However, the posting Event Manager sets the modifiers field of the 
high-level event record to one of the following values: 


CONST msgWasNotAccepted = 0; 
msgwasFullyAccepted = 1; 
2; 


msgWasPartiallyAccepted 


The msgWasNotAccepted constant indicates that your event was not accepted by 

the receiving application. This means that the receiving application was notified 

of the arrival of your event (through WaitNextEvent) but did not call 
AcceptHighLevelEvent to accept the event. The msgWasFullyAccepted constant 
indicates that the receiving application did call AcceptHighLevelEvent and retrieved 
all the data in the optional data buffer. The msgWasPartiallyAccepted constant 
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indicates that the receiving application called AcceptHighLevelEvent, but the 
application’s data buffer was too small to hold the data sent with your application, and 
the receiving application called WaitNextEvent before retrieving the rest of the buffer. 





Note that a return receipt does not indicate the identity of the receiving application. To 
determine on whose behalf the Event Manager has sent you a particular return receipt, 
you need to call AcceptHighLevelEvent. When AcceptHighLevelEvent returns 
successfully, the sender parameter contains a target ID record with the fields filled in 
for the receiving application. With return receipts, the msgLen parameter is 0, the 
msgBuff parameter is NIL, and the msgRefCon parameter contains the unique number 
of the refCon parameter of the original high-level event sender (that is, your 
application). 





Handling Apple Events 


If your application uses high-level events, your application must respond to the 
required Apple events sent by the Finder. The four required Apple events are Open 
Application, Open Documents, Print Documents, and Quit Application. See Inside 
Macintosh: Interapplication Communication for information on how to handle the required 
Apple events. 


When your application receives a high-level event (as indicated by the 
kHighLevelEvent constant in the what field of the event record), and if your 
application supports Apple events, call the AEProcessAppleEvent function. The 
AEProcessAppleEvent function provides an easy way for your application to identify 
the event class and event ID of the Apple event and to direct the Apple Event Manager 
to call the code in your program that handles the Apple event. 




















To send Apple events to other applications, use the AESend function. 


To ensure compatibility and smooth interaction with other Macintosh applications, you 
should use the Apple event protocol for high-level events whenever possible. By 
implementing the capabilities to send Apple events to and receive Apple events from 
other applications, you allow other applications to interact with your application and 
provide enhanced capabilities to your users. 


See Inside Macintosh: Interapplication Communication for complete information on how to 
send and receive Apple events. 
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This section describes the data structures and routines for the Event Manager and 
Operating System Event Manager. It also describes the 'SIZE' resource. 
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Data Structures 


This section describes the event record, target ID record, high-level event message 
record, and structure of the Operating System event queue. The Event Manager 

uses event records to return information about events. You can use a target ID record 
to specify or identify the address of another application or process with which your 
application is communicating. If your application supplies a filter function as a 
parameter to the Get SpecificHighLevelEvent function, your filter function 
receives information about high-level events in a high-level event message record. 


The Event Record 


When your application uses an Event Manager routine to retrieve an event, the Event 
Manager returns information about the retrieved event in an event record. The 
EventRecord data type defines the event record. 





TYPE EventRecord = 











RECORD 
what: Integer; {event code} 
message: LongInt; {event message} 
when: LongInt; {ticks since startup} 
where: Point; {mouse location} 
modifiers: Integer; {modifier flags} 

END; 


Field descriptions 
what The what field indicates the type of event received. The type of 
event can be identified by these constants: 


CONST 

nullEvent = 0; {no other pending events} 
mouseDown = 1; {mouse button pressed} 
mouseUp ; {mouse button released} 


0 

1 

2: 

keyDown 3; {key pressed} 
keyUp = 4; {key released} 
autoKey = 5; {key repeatedly held down} 
updateEvt 6; {window needs updating} 
diskEvt 7 
activateEvt = 8 
osEvt = 1 








; {disk inserted} 
; {activate/deactivate window} 
5; {operating-system event-—- } 
{ resume, suspend, or } 
{ mouse-moved} 
kHighLevelEvent = 23; {high-level event} 


Note that in System 7, event types with the values 9 through 14 are 
undefined and reserved for future use by Apple. All other values 
for the what field are also reserved for use by Apple. 
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message 


when 


where 


modifiers 


Additional information associated with the event. The interpreta- 
tion of this information depends on the event type. The contents of 
the message field for each event type are summarized here: 


Event type 


null, mouse-up, 
mouse-down 


key-up, 
key-down, 
auto-key 


update, activate 
disk-inserted 


resume 


suspend 


mouse-moved 


high-level 


Event message 
Undefined. 


Character code and virtual key code in 
low-order word. For Apple Desktop Bus 
(ADB) keyboards, the low byte of the 
high-order word contains the ADB address 
of the keyboard where the keyboard event 
occurred. The high byte of the high-order 
word is reserved. 


Pointer to the window to update, activate, or 
deactivate. 


Drive number in low-order word, File 
Manager result code in high-order word. 





The suspendResumeMessage constant in 
bits 24-31 and a 1 in bit 0 to indicate the 
event is a resume event. Bit 1 contains either 
a1 ora 0 to indicate if Clipboard conversion 
is required, and bits 2-23 are reserved. 





The suspendResumeMessage constant in 
bits 24-31 and a 0 in bit 0 to indicate the 
event is a suspend event. Bit 1 is undefined, 
and bits 2-23 are reserved. 


The mouseMovedMessage constant in bits 
24-31. Bits 2-23 are reserved, and bit 0 and 
bit 1 are undefined. 


Class of events to which the high-level event 
belongs. The message and where fields of 

a high-level event define the specific type of 
high-level event received. 


The when field indicates the time when the event was posted (in 
ticks since system startup). 


For low-level events and operating-system events, the where field 
contains the location of the cursor at the time the event was posted 
(in global coordinates). 


For high-level events, the where field contains a second event 
specifier, the event ID. The event ID defines the particular type of 
event within the class of events defined by the message field of the 
high-level event. For high-level events, you should interpret the 
where field as having the data type OSType, not Point. 

The modifiers field contains information about the state of the 


modifier keys and the mouse button at the time the event was 
posted. For activate events, this field also indicates whether the 
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The Target ID Record 


window should be activated or deactivated. In System 7 it also 
indicates whether the mouse-down event caused your application 
to switch to the foreground. 


Each of the modifier keys is represented by a specific bit in the 
modifiers field of the event record. Figure 2-5, on page 2-20, 
shows how to interpret the modifiers field. The modifier keys 
include the Option, Command, Caps Lock, Control, and Shift keys. 
If your application attaches special meaning to any of these keys in 
combination with other keys or when the mouse button is down, 
you can test the state of the modifiers field to determine the 
action your application should take. For example, you can use this 
information to determine whether the user pressed the Command 
key and another key to make a menu choice. 


When you send a high-level event to another application, you can use the target ID 


record to specify the 


recipient of the event. When you receive a high-level event, the 





AcceptHighLevel! 
the sender of the eve 


The Target ID data 


Event function uses a target ID record to return information about 
nt. 


type defines the target ID record. 


TYPE TargetID = 





RECORD 
sessionID: LongInt; {session reference number} 
name: PPCPortRec; {port name} 
location: LocationNameRec; {location name} 
recvrName: PPCPortRec; {reserved} 
END; 


Field descriptions 
sessionID 


name 


For high-level events that your application receives, this field 
contains the session reference number created by the PPC Toolbox. 
This is a 32-bit number that uniquely identifies a PPC Toolbox 
session (or connection) with another application. This field is not 
used by your application when sending a high-level event to 
another process. (To send a high-level event that specifies the 
recipient by session reference number, provide a pointer to a session 
reference number in the receiverID parameter and use the 
receiverIDisSessionID constant in the postingOptions 
parameter to PostHighLevelEvent.) 


For high-level events that your application receives, this field 
contains a PPC port record that specifies the port name of the 
process from which the high-level event originated. When sending 
a high-level event to a process on a local or remote computer, you 
can specify the port name of the recipient process in a PPC port 
record that you provide in this field. 
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If the sending application is on the same computer as the 
receiving application, you can determine the sending 
application’s process serial number by calling the 
GetProcessSerialNumberFromPortName function. 


location For high-level events that your application receives, this field 
contains a location name record that identifies the location name 
of the process from which the high-level event originated. When 
sending a high-level event to a process on a local or remote 
computer, you can specify the location name of the recipient process 
in a location name record that you provide in this field. 


recvrName This field is reserved. 


The High-Level Event Message Record 
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You can search your application’s high-level event queue for a specific high-level event 
by using the Get SpecificHighLevelEvent function and providing a filter function. 
Your filter function receives a pointer to a high-level event message record that contains 
information about a high-level event. (See “Filter Function for Searching the High-Level 
Event Queue” on page 2-114 for information on how to define a filter function.) 





The HighLevelEventMsg data type defines the structure of a high-level event 
message record. 


TYPE HighLevelEventMsg = 








RECORD 
HighLevelEventMsgHeaderLength: Integer; 
version: Integer; 
reservedl: LongInt; 
theMsgEvent: EventRecord; 
userRefCon: LongInt; 
postingOptions: LongIint; 
msgLength: LongInt; 

END; 





Field descriptions 


HighLevelEventMsgHeaderLength 
Reserved for use by the Event Manager. 


version Reserved for use by the Event Manager. 
reservedl Reserved for use by the Event Manager. 
theMsgEvent The event record of a high-level event. Your filter function can 





compare the fields of this event record to determine whether the 
high-level event is the desired event. If your filter function finds the 
desired event, it should call AcceptHighLevelEvent to accept 
the event and remove the event from the high-level event queue, 
and return TRUE as its function result. 
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userRefCon A unique number that identifies the communication associated with 
this event. 


postingOptions Reserved for use by the Event Manager. 
msgLength Reserved for use by the Event Manager. 


The Event Queue 


The event queue is a standard Macintosh Operating System queue that the Operating 
System Event Manager maintains. Only mouse-up, mouse-down, key-up, key-down, 
auto-key, and disk-inserted events are stored in the Operating System event queue. In 
most cases, your application should not access the event queue directly. Instead you 
usually use the WaitNextEvent function, which can retrieve events from this queue as 
well as from other sources. 


The event queue consists of a header followed by the actual entries in the queue. The 
event queue has the same header as all standard Macintosh Operating System queues. 
The Qhdr data type defines the queue header. 





TYPE QHdr = 
RECORD 
qFlags: Integer; {queue flags} 
qHead: QElemPtr; {first queue entry} 
qTail: QElemPtr; {last queue entry} 
END; 





The EvQE1 data type defines an entry in the Operating System event queue. 





TYPE EvQE1 = 














RECORD 
qhLink: QElemPtr; {next queue entry} 
qType: Integer; {queue type (ORD (evType) ) } 
evtQWhat: Integer; {event code} 
evtQMessage: LongInt; {event message} 
evtQWhen: LongIint; {ticks since startup} 
evtQWhere: Point; {mouse location} 
evtQModifiers: Integer; {modifier flags} 

END; 


Each entry in the event queue begins with 4 bytes of flags followed by a pointer to the 
next queue entry. The flags are maintained by and internal to the Operating System 
Event Manager. The queue entries are linked by pointers, and the first field of the EvQE1 
data type, which represents the structure of a queue entry, begins with a pointer to the 
next queue entry. Thus you cannot directly access the flags using the EvQE1 data type. 
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Event Manager Routines 


The Event Manager includes routines for receiving events, receiving and sending 
high-level events, and searching for specific high-level events. The Event Manager also 
provides routines for converting between process serial numbers and port names, 
getting information about the state of the mouse button, reading the keyboard, and 
getting timing information. 


Receiving Events 
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You can use the WaitNextEvent or GetNextEvent function to retrieve an event from 
the Event Manager and remove the event from the event stream. To provide greater 
support for multitasking, however, you should use the WaitNextEvent function 
instead of GetNextEvent whenever possible. You can use the EventAvail function 
to look at an event without removing it from the event stream. You can use the 
AcceptHighLevelEvent function to get additional information associated with a 
high-level event and Get SpecificHighLevelEvent to search for a specific high- 
level event. 








The FlushEvents procedure removes all low-level events from the Operating System 
event queue. In general, your application should not empty the event queue. 


You can use the SystemClick procedure to route events to desk accessories when 
necessary. The SystemTask and SystemEvent routines are used by the Event 
Manager, and your application usually does not need to call these two routines. 





You usually use the functions provided by the Toolbox Event Manager to retrieve events 
from the event stream. Even if you are interested only in the events stored in the 
Operating System event queue, you can retrieve these events using the Toolbox Event 
Manager by setting the event mask to mask out all events except keyboard, mouse, and 
disk-inserted events. However, you can choose to use Operating System Event Manager 
routines to perform this task. 





The Operating System Event Manager provides two functions, GetOSEvent and 
OSEventAvail, to retrieve events from the Operating System event queue. In most 
cases, your application will not need to use these two functions. 





If your application needs to receive key-up events, you can change the system event 
mask of your application using the SetEventMask procedure. The GetEvQHdr 
function returns a pointer to the header of the Operating System event queue. 
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WaitNextEvent 





You can use the WaitNextEvent function to retrieve events one at a time from the 
Event Manager. 


FUNCTION Wa 


eventMask 


theEvent 





itNextEvent (eventMask: Integer; 








VAR theEvent: EventRecord; sleep: LongInt; 
mouseRgn: RgnHandle): Boolean; 


A value that indicates which kinds of events are to be returned; this 
parameter is interpreted as a sum of event mask constants. You can use 
these constants to specify the event mask: 


CONST 
mDownMask = 2; {mouse-down event (bit 1)} 
mUpMask = 4; {mouse-up event (bit 2) } 
keyDownMask = 8; {key-down event (bit 3) } 
keyUpMask = 16; {key-up event (bit 4) } 
autoKeyMask = 32; {auto-key event (bit 5) } 
updateMask = 64; {update event (bit 6) } 
diskMask = 128; {disk-inserted event (bit 7)} 
activMask = 256; {activate event (bit 8) } 
highLevelEventMask 

= 1024; {high-level event (bit 10) } 
osMask = -—32768; {operating-system (bit 15) } 


To accept all events, you can specify the everyEvent constant as the 
event mask: 


CONST 


everyEvent = -l; {every event} 





If no event of any of the designated types is available, WaitNextEvent 
returns a null event. WaitNextEvent determines the next available 
event to return based on the eventMask parameter and the priority of 
the event. 








Events not designated by the event mask remain in the event stream until 
retrieved by an application. Low-level events in the Operating System 
event queue are kept in the queue until they are retrieved by your 
application or another application or until the queue becomes full. Once 
the queue becomes full, the Operating System Event Manager begins 
discarding the oldest events in the queue. 


The next available event of the specified type or types. The 
WaitNextEvent function removes the returned event from the event 
stream and returns the information about the event in an event record. 
The event record includes the type of event received and other 
information. See “The Event Record,” beginning on page 2-79, for a 
description of the fields in the event record. 
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In addition to the event record, high-level events can contain additional 
data; you use the AcceptHighLevelEvent or AEProcessAppleEvent 
functions to get additional data associated with these events. 


sleep The number of ticks (a tick is approximately '/60 of a second) indicating 
the amount of time your application is willing to relinquish the processor 
if no events (other than null events) are pending for your application. If 
you specify a value greater than 0 for the sleep parameter, your 
application relinquishes the processor for the specified time or until an 
event occurs. 


You should usually specify a value greater than 0 for the sleep 
parameter to allow background processes to receive processing time. You 
should not set the sleep parameter to a value greater than the number of 
ticks returned by Get CaretTime if your application provides 
text-editing capabilities. When the specified time expires, and if there are 
no pending events for your application, WaitNextEvent returns a null 
event in the parameter theEvent. 








mouseRgn A handle toa region that specifies a region inside of which mouse 
movement does not cause mouse-moved events. In other words, your 
application receives mouse-moved events only when the cursor is outside 
the specified region. You should specify the region in global coordinates. 
If you pass an empty region or a NIL region handle, the Event Manager 
does not report mouse-moved events to your application. Note that your 
application should recalculate the mouseRgn parameter when it receives 
a mouse-moved event, or it will continue to receive mouse-moved events 
as long as the cursor position is outside the original mouseRgn. 


The WaitNextEvent function retums FALSE as its function result if the event being 
returned is a null event or if WaitNextEvent has intercepted the event; otherwise, 
WaitNextEvent returns TRUE. The WaitNextEvent function calls the Operating 
System Event Manager function SystemEvent to determine whether the event should 
be handled by the application or the Operating System. 


If no events are pending for your application, WaitNextEvent waits for a specified 
amount of time for an event. (During this time, processing time may be allocated to 
background processes.) If an event occurs, it is returned as the value of the parameter 
theEvent, and WaitNextEvent returns a function result of TRUE. If the specified 
time expires and there are no pending events for your application, WaitNextEvent 
returns a null event in theEvent and a function result of FALSE. 





Before returning an event to your application, WaitNextEvent performs other 
processing and may intercept the event. 


The WaitNextEvent function intercepts Command-Shift-number key sequences and 
calls the corresponding 'FKEY' resource to perform the associated action. The Event 
Manager’s processing of Command-Shift-number key sequences with numbers 3 
through 9 can be disabled by setting the ScrDmpEnab1e global variable (a byte) to 0. 








The WaitNextEvent function also makes the alarm go off if the alarm is set and 
the current time is the alarm time. The user sets the alarm using the Alarm Clock 
desk accessory. 
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The WaitNextEvent function also calls the SystemTask procedure, which gives time 
to each open desk accessory or device driver to perform any periodic action defined 

for it. A desk accessory or device driver specifies how often the periodic action should 
occur, and SystemTask gives time to the desk accessory or device driver at the 
appropriate interval. 


Some high-level events may be fully specified by their event records only, while others 
may include additional information in an optional buffer. To get any additional 
information and to find the sender of the event, use the Accept HighLevelEvent 
function. 





If the returned event is a high-level event and your application supports Apple events, 
use the Apple Event Manager function AEProcessAppleEvent to respond to the 
Apple event and to get additional information associated with the Apple event. 





SPECIAL CONSIDERATIONS 


In System 7, if your application is in the foreground and the user opens a desk accessory 
or other item from the Apple menu, clicks in the window belonging to another 
application or desk accessory, or chooses another process from the Application menu, the 
next event reported to your application by the WaitNextEvent function is a suspend 
event. After your application is switched out, the Event Manager directs events (other 
than events your application can receive in the background) to the newly activated 
process until the user switches back to your application or another application. 


Note 

In a single-application environment in System 6, and in a multiple- 
application environment in which the desk accessory is launched in 

the application’s partition (for example, a desk accessory opened by the 
user from the Apple menu while holding down the Option key), the 
Event Manager handles events for desk accessories in a slightly 
different manner. 


In these environments, when mouse-up, activate, update, and keyboard 
events (including keyboard equivalents of menu commands) occur, the 
Event Manager checks to see whether the active window belongs to a 
desk accessory and whether the desk accessory can handle the event. If 
so, it sends the event to the desk accessory and WaitNextEvent returns 
FALSE to your application. Also note that in these environments, the 
Event Manager returns TRUE for mouse-down events, regardless of 
whether the mouse-down event is for a desk accessory or not. For 
mouse-down events in these situations, if the mouse button was 

pressed while the cursor was in a desk accessory window (as indicated 
by the inSystem constant returned by the FindWindow function), 
your application should call the SystemClick procedure. The 
SystemClick procedure handles mouse-down events as appropriate 
for desk accessories, including sending your application an activate 
event to deactivate its front window if the desk accessory window needs 
to be activated. 
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For examples that use the WaitNextEvent function, see Listing 2-1 on page 2-23 and 
Listing 2-2 on page 2-24. 


To get information about the sender of a high-level event and to retrieve any 
additional data associated with the high-level event, see the description of the 
AcceptHighLevelEvent function on page 2-90. For details on how to process 
an Apple event, see the description of the AEProcessAppleEvent function in 
Inside Macintosh: Interapplication Communication. 








For information on how to retrieve an event without removing it from the event stream, 
see the description of the EventAvail function, immediately following. 


EventAvail 
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You can use the EventAvail function to retrieve the next available event from 
the Event Manager without removing the returned event from your application’s 
event stream. 


FUNCTION EventAvail (eventMask: Integer; 
VAR theEvent: EventRecord): Boolean; 


eventMask A value that indicates which kinds of events are to be returned; this 
parameter is interpreted as a sum of event mask constants. You can use 
these constants to specify the event mask: 





CONST 
mDownMask = 2; {mouse-down event (bit 1)} 
mUpMask = 4; {mouse-up event (bit 2) } 
keyDownMask = 8; {key-down event (bit 3) } 
keyUpMask = 16; {key-up event (bit 4) } 
autoKeyMask = 32; {auto-key event (bit 5) } 
updateMask = 64; {update event (bit 6) } 
diskMask = 128; {disk-inserted event (bit 7)} 
activMask = 256; {activate event (bit 8) } 
highLevelEventMask 

= 1024; {high-level event (bit 10) } 
osMask = -32768; {operating-system (bit 15) } 





To accept all events, you can specify the everyEvent constant as the 
event mask: 


CONST 


everyEvent = -l; {every event} 





If no event of any of the designated types is available, EventAvail 
returns a null event. 


Event Manager Reference 


CHAPTER 2 


Event Manager 





theEvent 


DESCRIPTION 


EventAvail returns FALS! 
event; otherwise, EventAvail returns TRUE. 


Like WaitNextEvent, the ] 





The next available event of the specified type or types. The EventAvail 
function does not remove the returned event from the event stream, but 
does return the information about the event in an event record. The event 
record includes the type of event received and other information. 














E as its function result if the event being returned is a null 


EventAvail function calls the SystemTask procedure to 


give time to each open desk accessory or device driver to perform any periodic action 


defined for it. The | 





EventAvail function also makes the alarm go off if the alarm is set 


and the current time is the alarm time. The user sets the alarm using the Alarm Clock 
desk accessory. 


SPECIAL CONSIDERATIONS 


If EventAvail returns a low-level event from the Operating System event queue, the 
event will not be accessible later if, in the meantime, the event queue becomes full and 
the event is discarded from it; however, this is not a common occurrence. 


SEE ALSO 


See “The Event Record,” beginning on page 2-79, for a description of the fields in the 


event record. 


GetNextEvent 


Although you should normally use WaitNextEvent, you can also use the 
GetNextEvent function to retrieve events one at a time from the Event Manager. 





FUNCTION GetNextEvent (eventMask: Integer; 
VAR theEvent: EventRecord): Boolean; 


eventMask 


theEvent 











A value that indicates which kinds of events are to be returned; this 
parameter is interpreted as a sum of event mask constants (listed in 
“Setting the Event Mask” beginning on page 2-26). If no event of any of 


the designated types is available, GetNext! 


The next available event of the specified type 


Event returns a null event. 
or types. The 





GetNextEvent function removes the returned event from the 
event stream and returns the information about the event in an 
event record. The event record includes the type of event received 


and other information. 
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GetNextEvent returns FALSE as its function result if the event being returned is a null 
event or if GetNextEvent has intercepted the event; otherwise, GetNextEvent returns 
TRUE. The GetNextEvent function calls the Operating System Manager function 
SystemEvent to determine whether the event should be handled by the application or 
the Operating System. 




















Like WaitNextEvent, the GetNextEvent function calls the Syst emTask procedure to 
give time to each open desk accessory or device driver to perform any periodic action 
defined for it. The GetNextEvent function also makes the alarm go off if the alarm is 
set and the current time is the alarm time. (The user sets the alarm using the Alarm Clock 
desk accessory.) 





The GetNextEvent function also intercepts Command-Shift-number key sequences 
and calls the corresponding 'FKEY' resource to perform the associated action. The Event 
Manager’s processing of Command-Shift-number key sequences with numbers 

3 through 9 can be disabled by setting the ScrDmpEnab1e global variable (a byte) to 0. 








SPECIAL CONSIDERATIONS 


SEE ALSO 


For greater support of the multitasking environment, your application should use 
WaitNextEvent instead of GetNextEvent whenever possible. If your application 
does call GetNext Event, it should also call the SystemTask procedure. 


See “The Event Record,” beginning on page 2-79, for a description of the fields in the 
event record. For information on the SystemTask procedure, see page 2-95. 


AcceptHighLevelEvent 
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After receiving a high-level event (other than an Apple event), use the 
AcceptHighLevelEvent function to get any additional information associated 
with the event. 





FUNCTION AcceptHighLevelEvent (VAR sender: TargetID; 
VAR msgRefcon: LongInt; 





msgBuff: Ptr; 





VAR msgLen: LongInt): OSErr; 


sender Identifies the sender of the event; this information is returned in a target 
ID record. The sender parameter contains the session reference number 
that identifies the connection with the other application and the port 
name and location name of the sender. 
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msgRefcon Uniquely identifies the communication associated with this event. If you 
send a response to this event, you should specify the same value for the 
msgRefcon parameter so that the sender of the event can associate the 
reply with the original request. 








msgBuff Specifies where the AcceptHighLevelEvent function should return 
any additional data associated with the event. Your application is 
responsible for allocating the memory for the additional data pointed 
to by the msgBuff parameter and for setting the msgLen parameter to 
the number of bytes that you have allocated for the data. 





If the msgBuff parameter points to an area in memory that is 

not large enough to hold all the data associated with the event, 
AcceptHighLevelEvent returns as much data as the specified 
memory area can hold, returns the amount of data remaining in the 
msgLen parameter, and returns the result code bufferIsSmall. 





msgLen Contains the size of the data (in bytes) pointed to by the msgBuff 
parameter. If AcceptHighLevelEvent returns the result code 
bufferIsSmall1, the msgLen parameter contains the number of bytes 
remaining. You can call AcceptHighLevelEvent again to receive the 
rest of the data. 








DESCRIPTION 


When your application receives a high-level event, you can use the 
AcceptHighLevelEvent function to get additional data associated with the 
event. The AcceptHighLevelEvent function returns information that identifies 
the sender of the event and the unique message reference constant of the event. 





Your application should allocate memory for any additional data associated with the 
event, then supply a pointer to the data area and also provide the length in bytes of the 
data area. 


SPECIAL CONSIDERATIONS 


The AcceptHighLevelEvent function may move or purge memory. You should not 
call this function from within an interrupt, such as in a completion routine or VBL task. 


ASSEMBLY-LANGUAGE INFORMATION 





The trap macro and routine selector for the AcceptHighLevelEvent function are 
Trap macro Selector 
_OSDispatch $0033 








RESULT CODES 
noErr 0 No error 
bufferIsSmall —607 Buffer is too small 
noOut standingHLE -608 No outstanding high-level event 
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For details on how to process an Apple event using the AEProcessAppleEvent 
function, see Inside Macintosh: Interapplication Communication. 


GetSpecificHighLevelEvent 


DESCRIPTION 
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You can use the Get SpecificHighLevelEvent function to select and optionally 
retrieve a specific high-level event from your application’s high-level event queue. 


FUNCTION GetSpecificHighLevelEvent 
(aFilter: GetSpecificFilterProcPtr; 
yourDataPtr: UNIV Ptr; VAR err: OSErr): Boolean; 








aFilter Specifies the filter function that Get SpecificHighLevelEvent should 
use to search for a specific event. Get SpecificHighLevelEvent calls 
your filter function once for each event in your application’s high-level 
event queue until your filter function returns TRUE or the end of the 
queue is reached. 








yourDataPtr 
Specifies the criteria your filter function should use to select a specific 
event. For example, in the yourDataPtr parameter you can specify a 
reference constant to search for a particular event, a pointer to a target ID 
record to search for a specific sender of an event, or an event class to 
search for a specific class of event. 


err Get SpecificHighLevelEvent returns in this parameter a value 
indicating if any errors occurred. The err parameter contains the noErr 
constant if no errors occurred or noOut standingHLE if no high-level 
events are pending in your application’s high-level event queue. 





You can use the Get SpecificHighLevelEvent function to search for a specific 
high-level event in your application’s high-level event queue. You provide a pointer to a 
filter function as one of the parameters to Get SpecificHighLevelEvent. The 

Get SpecificHighLevelEvent function calls your filter function once for every event 
in your application’s high-level event queue, until your filter function returns TRUE or 
the end of the queue is reached. 








The Get SpecificHighLevelEvent function passes the value you specify in the 
yourDataPtr parameter to your filter function. Your filter function also receives as 
parameters the event record associated with the high-level event and the target ID record 
that identifies the sender of the event. Your filter function can compare the contents of 
the yourDataPtr parameter with any of the other information it receives. 


If your filter function finds a match, it can call AcceptHighLevelEvent if necessary, 
and then return TRUE. If your filter function does not find a match, then it should 
return FALSE. 
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If your filter function returns TRUE, the Get SpecificHighLevelEvent function 
returns TRUE. If your filter function returns FALSE for all high-level events in your 
application’s event queue, or if there are no high-level events in the queue, 
GetSpecificHighLevelEvent returns FALSE. 














SPECIAL CONSIDERATIONS 


The Get SpecificHighLevelEvent function may move or purge memory. You 
should not call this function from within an interrupt, such as in a completion routine 
or VBL task. 


ASSEMBLY-LANGUAGE INFORMATION 


The trap macro and routine selector for the Get SpecificHighLevelEvent 
function are 


Trap macro Selector 
_OSDispatch $0045 


SEE ALSO 
See “Filter Function for Searching the High-Level Event Queue” on page 2-114 for more 
information about how to define a filter function and the parameters that 
Get SpecificHighLevelEvent passes to your filter function. 

FlushEvents 


The FlushEvents procedure removes low-level events from the Operating System 
event queue. Note that FlushEvents does not remove any types of events not stored 
in the Operating System event queue. 





You can choose to use the F lushEvents procedure when your application first starts to 
empty the Operating System event queue of any keystrokes or mouse events generated 
by the user while the Finder loaded your application. In general, however, your 
application should not empty the queue at any other time as this loses user actions and 
makes your application and the computer appear unresponsive to the user. 





PROCEDURE FlushEvents (whichMask: Integer; stopMask: Integer) ; 








whichMask A value that indicates which kinds of low-level events are to be removed 
from the Operating System event queue; this parameter is interpreted 
as a sum of event mask constants. The whichMask and stopMask 
parameters together specify which events to remove. 
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stopMask A value that limits which low-level events are to be removed from the 
Operating System event queue; this parameter is interpreted as a sum 
of event mask constants. F lushEvents does not remove any low- 
level events that are specified by the stopMask parameter. To remove 
all events specified by the whichMask parameter, specify 0 as the 
stopMask parameter. 


FlushEvents removes only low-level events stored in the Operating System event 
queue; it does not remove activate, update, operating-system, or high-level events. 


You specify which low-level events to remove using the whichMask and stopMask 
parameters. FlushEvents removes the low-level events specified by the whichMask 
parameter, up to but not including the first event of any type specified by the 
stopMask parameter. 


If the event queue doesn’t contain any of the events specified by the whichMask 
parameter, FlushEvents does not remove any events from the queue. 





ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 


You must set up register DO with the event mask (whichMask) and stop mask before 
calling FlushEvents. When FlushEvents returns, register DO contains 0 if all events 
were removed from the queue or, if all events were not removed from the queue, an 
event code that specifies the type of event that caused the removal process to stop. 








Registers on entry 
DO Event mask (low-order word) 


Stop mask (high-order word) 


Registers on exit 


DO 0 if all events were removed from the queue, or the event code 
of the event that stopped the search (low-order word) 


See “Setting the Event Mask” beginning on page 2-26 for information on how to specify 
an event mask. 


SystemClick 
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After receiving a mouse-down event, your application should call the Window 
Manager function F indWindow to determine where the cursor was when the mouse 
button was pressed. If FindWindow returns the inSysWindow constant, call the 
SystemClick procedure to handle the event. 


PROCEDURE SystemClick (theEvent: EventRecord; 
theWindow: WindowPtr) ; 
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theEvent The event record for the event. 


theWindow The window in which the mouse-down event occurred. Pass the window 
pointer returned by FindWindow in this parameter. 


If a mouse-down event occurred in a desk accessory’s window, the SystemClick 
procedure determines which part of the desk accessory’s window the cursor was in 
when the mouse button was pressed and routes the event to the appropriate desk 
accessory as necessary. 


If the mouse button was pressed while the cursor was in the content region of the desk 
accessory’s window and the window is active, SystemClick sends the mouse-down 
event to the desk accessory to process. If the mouse-down event occurred in the content 
region of the window and the window is inactive, SystemClick makes it the active 
window. It does this by sending your application an activate event to deactivate its 
front window and directing an event to the desk accessory to activate its window. 


If the mouse button was pressed while the cursor was in the drag region or go-away 
region, SystemClick calls the Window Manager routine DragWindow or 
TrackGoAway, as appropriate. If TrackGoAway reports that the user closed the desk 
accessory, SystemClick sends a close message to the desk accessory. 


See “The Event Record,” beginning on page 2-79, for a description of the fields in the 
event record. 





In a multiple-application environment, the WaitNextEvent function is responsible for 
giving time to each open desk accessory or driver to perform any periodic action. You 
should not call SystemTask if your application calls WaitNextEvent. 





If your application calls GetNextEvent, your application should call the SystemTask 
procedure. 


PROCEDURE SystemTask; 


The SystemTask procedure gives time to each open desk accessory or driver to 
perform the periodic action defined for it. A desk accessory or device driver specifies 
how often the periodic action should occur, and SystemTask gives time to the desk 
accessory or device driver at the appropriate interval. 


If your application calls GetNextEvent, your application should call SystemTask at 
least every sixtieth of a second. This usually corresponds to calling SystemTask once 
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each time through your event loop. If your application does a large amount of 
processing, you may need to call SystemTask more than once in your event loop. 














SEE ALSO 
For a description of the WaitNextEvent function and the GetNext Event function, see 
page 2-85 and page 2-89, respectively. 

SystemEvent 
The WaitNextEvent and GetNextEvent functions call the SystemEvent function. In 
most cases your application should not call the SystemEvent function. 
The SystemEvent function determines if a specific event should be handled by the 
application or the Operating System. 
FUNCTION SystemEvent (theEvent: EventRecord): Boolean; 
theEvent The event record for the event. 

DESCRIPTION 








SystemEvent returns FALSE as its function result if the event should be handled by the 
application; otherwise, SystemEvent takes any appropriate actions and returns TRUE. 





For activate, update, mouse-up, and keyboard events (including keyboard equivalents of 
commands), SystemEvent checks to see whether the active window belongs to a desk 
accessory and whether that desk accessory can handle that type of event. If so, 
SystemEvent sends the event to the desk accessory and returns TRUE. Otherwise, 
SystemEvent returns FALSE. 








For mouse-down events and null events, SystemEvent returns FALSE. 





For disk-inserted events, SystemEvent attempts to mount the disk using the 
PBMount Vol function but returns FALSE so that the application can perform further 
processing if necessary. 





ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 
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If the SEvtEnb global variable (a byte) contains 0, SystemEvent always returns FALSE. 


See “The Event Record,” beginning on page 2-79, for a description of the fields in the 
event record. For a description of the PBMount Vol function, see the chapter “File 
Manager” in Inside Macintosh: Files. 
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GetOSEvent 


The Toolbox Event Manager calls the Get OSEvent function to retrieve low-level events 
stored in the Operating System event queue. In most cases your application should not 
use this function. 


FUNCTION GetOSEvent (mask: Integer; 
VAR theEvent: EventRecord): Boolean; 





mask A value that indicates which kinds of events are to be returned; this 
parameter is interpreted as a sum of event mask constants. GetOSEvent 
returns only low-level events stored in the Operating System event 
queue; it does not return activate, update, operating-system, or high-level 
events. If no low-level event of any of the designated types is available, 
GetOSEvent returns a null event. 








theEvent The next available low-level event of the specified type or types in the 
Operating System event queue. The GetOSEvent function removes the 
returned event from the Operating System event queue and returns the 
information about the event in an event record. The event record includes 
the type of event received and other information. 





DESCRIPTION 


The GetOSEvent function retrieves and removes an event from the Operating System 
event queue. Get OSEvent returns FALSE as its function result if the event being 
returned is a null event; otherwise, GetOSEvent returns TRUE. GetOSEvent does not 
intercept or respond to the event in any way. It also does not process Command-Shift— 
number key combinations or process any alarms set by the user through the Alarm 
Clock desk accessory. 





ASSEMBLY-LANGUAGE INFORMATION 


You must set up register AO with the address of an event record and register DO with the 
event mask before invoking GetOSEvent. When Get OSEvent returns, register D0 
indicates whether the returned event is a null event or an event other than a null event 
and the returned event is accessible through register AO. 





Registers on entry 
AO Address of event record 


DO Event mask (low-order word) 


Registers on exit 
AO Address of event record 


DO 0 if GetOSEvent returns any event other than a null event, 
or —1 if it returns a null event (low-order byte) 
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SEE ALSO 
See “The Event Record,” beginning on page 2-79, for a description of the fields in the 
event record. See “Setting the Event Mask,” beginning on page 2-26, for information on 
how to specify an event mask. 
OSEventAvail 
The Toolbox Event Manager uses the OSEventAvail function to retrieve an event from 
the Operating System event queue without removing it. In most cases your application 
does not need to use this function. 
FUNCTION OSEventAvail (mask: Integer; 
VAR theEvent: EventRecord): Boolean; 
mask A value that indicates which kinds of events are to be returned; this 
parameter is interpreted as a sum of event mask constants. 
OSEventAvail returns only low-level events stored in the Operating 
System event queue; it does not return activate, update, operating-system, 
or high-level events. If no low-level event of any of the designated types 
is available, OSEventAvail returns a null event. 
theEvent The next available event of the specified type or types. The 
OSEventAvail function does not remove the returned event from the 
Operating System event queue but does return information about the 
event in an event record. The event record includes the type of event 
received and other information. 
DESCRIPTION 





The OSEventAvail function retrieves an event from the Operating System event queue 
without removing it from the queue. The OSEventAvail function returns FALSE as its 
function result if the event being returned is a null event; otherwise, OSEventAvail 
returns TRUE. 














OSEventAvail does not intercept or respond to the event in any way. It also does not 
process Command-Shift-number key combinations or process any alarms set by the 
user through the Alarm Clock desk accessory. 


SPECIAL CONSIDERATIONS 
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If the OSEventAvail function returns a low-level event from the Operating System 
event queue, the event will not be accessible later if, in the meantime, the event 
queue becomes full and the event is discarded from it; however, this is not a common 
occurrence. 
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ASSEMBLY-LANGUAGE INFORMATION 


You must set up register AO with the address of an event record and register DO with the 
event mask before invoking OSEventAvail. When OSEventAvail returns, register DO 
indicates whether the returned event is a null event or some other event, and the 
returned event is accessible through register AO. 








Registers on entry 
AO Address of event record 


DO Event mask (low-order word) 


Registers on exit 
AO Address of event record 





DO 0 if OSEventAvail returns any event other than a null event, 
or —1 if it returns a null event (low-order byte) 


SEE ALSO 


See “The Event Record,” beginning on page 2-79, for a description of the fields in the 
event record. See “Setting the Event Mask,” beginning on page 2-26, for information on 
how to specify an event mask 


SetEventMask 





The SetEventMask procedure sets the system event mask of your application to the 
specified mask. Your application should not call the SetEventMask procedure to 
disable any event types from being posted. Use SetEventMask only to enable key-up 
events if your application needs to respond to key-up events. 





PROCEDURE SetEventMask (theMask: Integer); 





theMask An event mask that specifies which events should be posted in the 
Operating System event queue. 


DESCRIPTION 





The SetEventMask procedure sets the system event mask of your application 
according to the parameter theMask. The Operating System Event Manager posts only 
low-level events (other than update or activate events) corresponding to bits in the 
system event mask of the current process when posting events in the Operating System 
event queue. The system event mask of an application is initially set to post mouse-up, 
mouse-down, key-down, auto-key, and disk-inserted events into the Operating System 
event queue. 
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ASSEMBLY-LANGUAGE INFORMATION 





The system event mask of the current application is available in the SysEvtMask system 


For additional information on event masks, see “Setting the Event Mask” beginning on 


GetEvOQHdr 





EvQHdr function to get a pointer to the header of the 


Operating System event queue. In most cases your application should not call the 


global variable. 
SEE ALSO 
page 2-26. 
The Event Manager uses the Get! 
GetEvQHdr function. 
FUNCTION GetEvQHdr: QHdrPtr; 
DESCRIPTION 





The Get EvQHdr function returns a pointer to the header of the Operating System 


event queue. 


ASSEMBLY-LANGUAGE NOTE 


The Event Queue system global variable contains the header of the event queue. 


SEE ALSO 


See “The Event Queue” on page 2-83 for information on the structure of the Operating 


System event queue. 


Sending Events 


You can send events to other applications or processes using the PostHighLevelEvent 
function. To send Apple events to other applications, use the Apple Event Manager 
function AESend. The Operating System Event Manager also provides the PPostEvent 
and PostEvent functions for posting low-level events to the Operating System event 
queue. The PostEvent function is used by the Toolbox Event Manager. In most cases 











your application should not use the PostEvent function. 
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PostHighLevelEvent 





You can use the PostHighLevelEvent function to send a high-level event to 
another application. 


FUNCTION PostHighLevelEvent (theEvent: EventRecord; 





theEvent 


receiverID 


msgRefcon 


msgBuff 


msgLen 


receiverID: Ptr; msgRefcon: LongInt; 





msgBuff: Ptr; msgLen: LongInt; 
postingOptions: LongInt): OSErr; 


The event to send. Your application should fill out the what, message, 
and where fields of the event record. Specify the kHighLevelEvent 
constant in the what field, the event class of the high-level event in the 
message field, and the event ID in the where field. You do not need to 
fill out the when or modifiers fields; the Event Manager automatically 
assigns the appropriate values to these fields when you send the message. 





The recipient of the high-level event. When sending an event to another 
application on the local computer, you can specify the recipient of the 
event by session reference number, process serial number, signature, or 
port name and location name. When sending an event to an application 
on a remote computer, you can specify the recipient only by the session 
reference number or by the port name and location name. 


To specify a port name and location name, provide the address of a target 
ID record in the receiverID parameter. To specify a process serial 
number, provide its address in the receiverID parameter. To specify a 
session reference number, or signature, provide the data (cast to the Ptr 
data type) in the receiverID parameter. 


A unique number that identifies the communication associated with this 
event. Your application can set this field to any value it chooses. If you are 
replying to a high-level event, you should use the same value in the 
msgRefcon parameter as specified in the high-level event that originated 
the request. 


A pointer to a data buffer that contains any additional data for the event. 


The size (in bytes) of the data buffer pointed to by the msgBuff 
parameter. 


postingOptions 


Options associated with the receiverID parameter and delivery options 
associated with the event. You can specify one or more delivery options to 
indicate whether you want the other application to receive the event at 
the next opportunity and to indicate whether you want acknowledgment 
that the event was received by the other application. You use the options 
associated with the receiverID parameter to indicate how you are 
specifying the recipient of the event—whether by port name and location 
name ina target ID record, by session reference number, by process serial 
number, or by signature. 
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You can use a combination of these constants in the post ingOptions 
parameter: 


CONST 
nAttnMsg 

= $00000001; {give this message priority} 
nReturnReceipt 

= $00000200; {return receipt requested} 
receiverIDisTargetID 





= $00005000; {ID is port name and location name} 
receiverIDisSessionID 

= $00006000; {ID is PPC session reference number} 
receiverIDisSignature 

= $00007000; {ID is creator signature} 
receiverIDisPSN 








= $00008000; {ID is process serial number} 


DESCRIPTION 
The PostHighLevelEvent function posts the high-level event to the specified process. 


If the application to which you are sending a high-level event terminates, you receive 
the result code sessionClosedErr the next time your application calls 
PostHighLevelEvent to send another high-level event to the terminated application. 
If you do not care about any state information about that session, you can just resend 
your event. Otherwise, you must restart another session and resend your event. 





If your application is running in the background and posts a high-level event that 
requires the network authentication dialog box to be displayed, PostHighLevelEvent 
returns the noUserInteract ionAl lowed result code, does not display the network 
authentication dialog box, and does not send the event. If your application receives the 
noUserInteractionAllowed result code, you can use the Notification Manager to 
inform the user that your application needs attention. When the user brings your 
application to the foreground, you can repost the event. If the reposting is successful, 
your application can continue to post high-level events without further user interaction. 
Note that PostHighLevelEvent can return noUserInteractionAllowed only on 
the first posting of a high-level event to a remote target. 





SPECIAL CONSIDERATIONS 


The PostHighLevelEvent function may move or purge memory. You should not call 
this function from within an interrupt, such as in a completion routine or VBL task. 


ASSEMBLY-LANGUAGE INFORMATION 
The trap macro and routine selector for the PostHighLevelEvent function are 
Trap macro Selector 
_OSDispatch $0034 
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RESULT CODES 


PPostEvent 


DESCRIPTION 
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For details on how to send Apple events to other applications using the AESend 
function, see Inside Macintosh: Interapplication Communication. 


noErr 0 No error 

connectionInvalid —609 Connection is invalid 
noUserInteractionAllowed —610 Cannot interact directly with user 
sessionClosedErr -917 Session closed 





In most cases your application does not need to post events in the Operating System 
event queue; however, if you must do so, you can use the PPostEvent function. 





FUNCTION PPostEvent (eventCode: Integer; eventMsg: LongInt; 
VAR gEl: EvQE1Ptr): OSErr; 




















eventCode A value that indicates the type of event to post into the Operating System 
event queue. The types of events that can be posted in this queue are 
represented by these constants: mouseDown, mouseUp, keyDown, keyUp, 
autoKey, and diskEvt. Do not attempt to post any other type of event 
in the Operating System event queue. 





eventMsg A long integer that contains the contents of the message field for the 
event that PPostEvent should post in the queue. 





gEL PPostEvent returns a pointer to the event queue entry of the posted 
event in this parameter. 





In the eventCode and eventMsg parameters, you specify the value for the what and 
message fields of the event’s event record. The PPostEvent function fills out the when, 
where, and modifiers fields of the event record with the current time, current mouse 
location, and current state of the modifier keys and mouse button. 





The PPostEvent function returns a pointer to the event queue entry of the posted event 
in the qE1 parameter. You can change any fields of the posted event by changing the 
fields of its event queue entry. For example, you can change the posted event’s modifier 
keys by changing the value of the evt QModifiers field of the event queue entry. 





The PPostEvent function posts only events that are enabled by the system event mask. 
If the event queue is full, PPostEvent removes the oldest event in the queue and posts 
the new event. 
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WARNING 

Do not post any events other than mouse-down, mouse-up, key-down, 
key-up, auto-key, and disk-inserted events in the Operating System 
event queue. Attempting to post other events into the Operating 
System event queue interferes with the internal operation of the 

Event Manager. A 


ASSEMBLY-LANGUAGE INFORMATION 


RESULT CODES 


SEE ALSO 


PostEvent 
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You must set up register AO and register DO before invoking PPostEvent. The 
PPostEvent function returns values in registers AO and D0. 





Registers on entry 
AO Event number (low-order word) 


DO Event message (long) 


Registers on exit 
AO Pointer to an event queue entry (long) 


DO Result code (low-order word) 


evtNotEnb 1 Event type not valid—event not posted 
noErr 0 No error 





For a description of the entries in the event queue, see “The Event Queue” on page 2-83. 





The Toolbox Event Manager uses the PostEvent function to post events into the 
Operating System event queue. In most cases your application should not call the 
PostEvent function. 


FUNCTION PostEvent (eventNum: Integer; eventMsg: LongInt): OSErr; 


eventNum A value that indicates the type of event to post into the Operating System 
event queue. The types of events that can be posted in this queue are 
represented by these constants: mouseDown, mouseUp, keyDown, keyUp, 
aut oKey, and diskEvt. Do not attempt to post any other type of event 
in the Operating System event queue. 





eventMsg A long integer that contains the contents of the message field for the 
event that PostEvent should post in the queue. 
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In the eventNum and eventMsg parameters, you specify the value for the what and 
message fields of the event’s event record. The PostEvent function fills out the when, 
where, and modifiers fields of the event record with the current time, current mouse 
location, and current state of the modifier keys and mouse button. 








The PostEvent function posts only events that are enabled by the system event mask. If 
the event queue is full, PostEvent removes the oldest event in the queue and posts the 
new event. 





Note that if you use PostEvent to repost an event, the PostEvent function fills out the 
when, where, and modifier fields of the event record, giving these fields of the 
reposted event different values from the values contained in the original event. 


WARNING 


Do not post any events other than mouse-down, mouse-up, key-down, 
key-up, auto-key, and disk-inserted events in the Operating System 
event queue. Attempting to post other events into the Operating 
System event queue interferes with the internal operation of the 

Event Manager. A 


ASSEMBLY-LANGUAGE INFORMATION 


RESULT CODES 


You must set up register AO with the event code and register DO with the event 
message before invoking PostEvent. When PostEvent returns, register DO 
contains the result code. 








Registers on entry 
AO Event number (low-order word) 


DO Event message (long) 


Registers on exit 





DO Result code (low-order word) 
evtNotEnb 1 Event type not valid—event not posted 
noErr 0 No error 





Converting Process Serial Numbers and Port Names 


The Event Manager provides two functions to convert between process serial 

numbers and port names (Get ProcessSerialNumberFromPortName and 
GetPortNameF romProcessSerialNumber). Both functions are intended to map 
serial numbers to port names (or vice versa) for applications open on the local computer. 
They do not return useful results for applications open on remote computers. 
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GetProcessSerialNumberFromPortName 


Use Get ProcessSerialNumberFromPortName to get the process serial number of a 
process. 


FUNCTION GetProcessSerialNumberFromPortName 
(portName: PPCPortRec; 
VAR PSN: ProcessSerialNumber): OSErr; 





portName The port name registered to a process whose serial number you want. 


PSN Returns the process serial number of the process designated by the 
portName parameter. You can use the returned process serial number to 
send a high-level event to that process. Do not interpret the value of the 
process serial number. 


DESCRIPTION 


The Get ProcessSerialNumberFromPortName function returns the process serial 
number of the process registered at a specific port. 


SPECIAL CONSIDERATIONS 


The Get ProcessSerialNumberFromPortName function does not move or purge 
memory but for other reasons should not be called from within an interrupt, such as 
in a completion routine or VBL task. 


ASSEMBLY-LANGUAGE INFORMATION 


The trap macro and routine selector for the 
GetProcessSerialNumberFromPortName function are 


Trap macro Selector 
_OSDispatch $0035 


RESULT CODES 


noErr 0 No error 
noPortErr —903 Invalid port name 








SEE ALSO 


For a description of the PPCPortRec data type, see the chapter “Program-to-Program 
Communications Toolbox” in Inside Macintosh: Interapplication Communication. 
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GetPortNameFromProcessSerialNumber 


Use Get PortNameF romProcessSerialNumber to get the port name of a process. 


FUNCTION GetPortNameFromProcessSerialNumber 
(VAR portName: PPCPortRec; 
PSN: ProcessSerialNumber): OSErr; 





portName Returns the port name of the process designated by the PSN parameter. 
You can use the returned port name to send a high-level event to 
that process. 


PSN The process serial number of the process whose port name you want. 


DESCRIPTION 


The Get PortNameF romProcessSerialNumber function returns the port name 
registered to a process having a specific process serial number. 


SPECIAL CONSIDERATIONS 


The Get PortNameF' romP rocessSerialNumber function does not move or purge 
memory but for other reasons should not be called from within an interrupt, such as 
in a completion routine or VBL task. 


ASSEMBLY-LANGUAGE INFORMATION 


The trap macro and routine selector for the 
GetPortNameFromProcessSerialNumber function are 


Trap macro Selector 
_OSDispatch $0046 





RESULT CODES 
noErr 0 No error 
procNotFound -600 No eligible process with specified process 
serial number 
SEE ALSO 


For a description of the PPCPortRec data type, see the chapter “Program-to-Program 
Communications Toolbox” in Inside Macintosh: Interapplication Communication. 
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Reading the Mouse 


GetMouse 


Button 


DESCRIPTION 


SEE ALSO 


2-108 


The Event Manager provides routines you can use to get information about the mouse. 
You can get the current mouse location using the GetMouse procedure. You can use 


the Button function to determine whether the user pressed the mouse button. After 





receiving a mouse-down event, you can use the St il1Down function to determine 
whether the mouse button is still down, and you can use WaitMouseUp to determine if 
the user subsequently released the mouse. 


You can use the GetMouse procedure to obtain the current mouse location. 





PROCEDURE GetMouse 











mouseLoc Returns the current mouse location in local coordinates of the current 


(VAR mouseLoc: Point) 


, 


graphics port (for example, the active window). Note that this value 


differs from the value of the where field of the event record, which 


specifies the mouse location in global coordinates. 





You can use the Button function to determine whether the user pressed the 


mouse button. 


FUNCTION Button: Bo 


olean; 


The Button function looks in the Operating System event queue for a mouse-down 





event. If it finds one, the | 


StillDown function. 





Button function returns TRU] 





E; otherwise, it returns FALS] 


See “The Event Queue” on page 2-83 for information about the Operating System 


event queue. 


Event Manager Reference 


.To 
determine whether the mouse button is still down after a mouse-down event, use the 


CHAPTER 2 


Event Manager 


StillDown 


After receiving a mouse-down event, you can use the St il1Down function to determine 
if the mouse button is still down. 





FUNCTION StillDown: Boolean; 


DESCRIPTION 


The Stil1lDown function looks in the Operating System event queue for a mouse 
event. If it finds one, the St il1Down function returns FALSE. If it does not find any 
mouse events pending in the Operating System event queue, the St il1Down function 
returns TRUE. 





SEE ALSO 


See “The Event Queue” on page 2-83 for information about the Operating System 
event queue. 


WaitMouseUp 


After receiving a mouse-down event, you can use the WaitMouseUp function to 
determine if the user subsequently released the mouse. 


FUNCTION WaitMouseUp: Boolean; 


DESCRIPTION 


The WaitMouseUp function looks in the Operating System event queue for a mouse-up 
event. If it finds one, the WaitMouseUp function removes the mouse-up event from the 
queue and returns TRUE. If it does not find any mouse events pending in the Operating 

System event queue, the WaitMouseUp function returns FALSE. 








SEE ALSO 


See “The Event Queue” on page 2-83 for information about the Operating System 
event queue. 
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Reading the Keyboard 


The Event Manager reports keyboard events one at a time at your application’s request 
when you use the WaitNextEvent, EventAvail, orGetNextEvent function. In 
addition to getting keyboard events when the user presses or releases a key, you can 
directly read the keyboard (and keypad) at any time using the Get Keys procedure. 

















You can also use the KeyTrans1late function to convert virtual key codes to character 
code values using a specified 'KCHR' resource. 














GetKeys 
You can use the Get Keys procedure to obtain the current state of the keyboard. 
PROCEDURE GetKeys (VAR theKeys: KeyMap) ; 
theKeys Returns the current state of the keyboard, including the keypad, if any. 
The Get Keys procedure returns this information using the KeyMap data 
type. 
TYPE KeyMap = PACKED ARRAY[0..127] OF Boolean; 
Each key on the keyboard or keypad corresponds to an element in the 
KeyMap array. The index for a particular key is the same as the key’s 
virtual key code minus 1. For example, the key with virtual key code 38 
(the “J” key on the Apple Keyboard II) can be accessed as KeyMap [37] in 
the returned array. A KeyMap element is TRUE if the corresponding key is 
down and FALSE if it isn’t. The maximum number of keys that can be 
down simultaneously is two character keys plus any combination of the 
five modifier keys. 
DESCRIPTION 
You can use the Get Keys procedure to determine the current state of the keyboard at 
any time. For example, you can determine whether one of the modifier keys is down by 
itself or in combination with another key using the Get Keys procedure. 
KeyTranslate 
You can use the KeyTranslate function to convert a virtual key code to a character 
code based on a 'KCHR' resource. The KeyTranslate function is also available as the 
KeyTrans function. 
FUNCTION KeyTranslate (transData: Ptr; keycode: Integer; 
VAR state: LongInt): LongInt; 
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transData A pointer to the 'KCHR' resource that you want the KeyTranslate 
function to use when converting the key code to a character code. 


keycode A 16-bit value that your application should set so that bits 0-6 contain the 
virtual key code and bit 7 contains either 1 to indicate an up stroke or 0 to 
indicate a down stroke of the key. Bits 8-15 have the same interpretation 
as the high byte of the modifiers field of the event record and should be 
set according to the needs of your application. 


state A value that your application should set to 0 the first time it calls 
KeyTranslate or any time your application calls KeyTranslate with 
a different 'KCHR' resource. Thereafter, your application should pass the 
same value for the state parameter as KeyTranslate returned in the 
previous call. 


The KeyTranslate function returns a 32-bit value that gives the character code for the 
virtual key code specified by the keycode parameter. Figure 2-17 shows the structure of 
the 32-bit number that KeyTranslate returns. 


Figure 2-17 Structure of the KeyTranslate function result 


Rewenred 1 Character ode 1 Reeerined 2 Characder code 2 





The KeyTranslate function returns the values that correspond to one or possibly two 
characters that are generated by the specified virtual key code. For example, a given 
virtual key code might correspond to an alphabetic character with a separate accent 
character. For example, when the user presses Option-E followed by N, you can map this 
through the KeyTranslate function using the U.S. 'KCHR" resource to produce ‘n, 
which KeyTranslate returns as two characters in the bytes labeled Character code 1 
and Character code 2. If KeyTranslate returns only one character code, it is always in 
the byte labeled Character code 2. However, your application should always check both 
bytes labeled Character code 1 and Character code 2 in Figure 2-17 for possible values 
that map to the virtual key code. 


For additional information on the 'KCHR' resource and the KeyTranslate function, 
see Inside Macintosh: Text. 
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Getting Timing Information 


You can get the current number of ticks since the system last started up using the 
TickCount function. You can use this function to compare the number of ticks that have 
expired since a given event or other action occurred. 


By using the GetDb1Time function, you can get the suggested maximum difference in 
ticks that should exist to consider two mouse events a double click. The user can adjust 
this value using the Mouse control panel. Using the Get Caret Time function you can 
get the suggested maximum difference in ticks that should exist between blinks of the 
caret in editable text. The user can adjust this value using the General Controls panel. 


TickCount 


You can use the TickCount function to get the current number of ticks (a tick is 
approximately '/60 of a second) since the system last started up. 


FUNCTION TickCount: LongInt; 


DESCRIPTION 


The TickCount function returns a long integer that indicates the current number of 
ticks since the system last started up. You can use this value to compare the number of 
ticks that have elapsed since a given event or other action occurred. For example, you 
could compare the current value returned by TickCount with the value of the when 
field of an event record. 


The tick count is incremented during the vertical retrace interrupt, but this interrupt can 
be disabled. Your application should not rely on the tick count to increment with 
absolute precision. Your application also should not assume that the tick count always 
increments by 1; an interrupt task might keep control for more than one tick. If your 
application keeps track of the previous tick count and then compares this value with the 
current tick count, your application should compare the two values by checking for a 
“greater than or equal” condition rather than “equal to previous tick count plus 1.” 


A WARNING 


Don’t rely on the tick count being exact; it’s usually accurate to within 
one tick, but this level of accuracy is not guaranteed. A 


ASSEMBLY-LANGUAGE NOTE 


The value returned by TickCount is also accessible in the global variable Ticks. 
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GetDbITime 


To determine whether a sequence of mouse events constitutes a double click, your 
application measures the elapsed time (in ticks) between a mouse-up event and a 
mouse-down event. If the time between the two mouse events is less than the value 
returned by Get Db1Time, your application should interpret the two mouse events 
as a double click. 


FUNCTION GetDblTime: LongInt; 


DESCRIPTION 


The GetDb1Time function returns the suggested maximum elapsed time, in ticks, 
between a mouse-up event and a mouse-down event. The user can adjust this value 
using the Mouse control panel. 


If your application distinguishes a double click of the mouse from a single click, your 
application should use the value returned by Get Db1Time to make this distinction. If 
your application uses TextEdit, the TextEdit procedures automatically recognize and 
handle double clicks of text within a TextEdit edit record by appropriately highlighting 
or unhighlighting the selection. 


ASSEMBLY-LANGUAGE NOTE 


The value returned by GetDb1Time is also accessible in the system global variable 
DoubleTime. 


GetCaretTime 


You can use the Get Caret Time function to get the suggested difference in ticks that 
should exist between blinks of the caret (usually a vertical bar marking the insertion 
point) in editable text. The user can adjust this value using the General Controls panel. 


FUNCTION GetCaretTime: LongInt; 


DESCRIPTION 


If your application supports editable text, your application should use the value 
returned by Get Caret Time to determine how often to blink the caret. If your 
application uses only TextEdit, you can use TextEdit procedures to automatically blink 
the caret at the time interval that the user specifies in the General Controls panel. 


ASSEMBLY-LANGUAGE NOTE 


The value returned by Get Caret Time is also accessible in the system global 
variable CaretTime. 
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Application-Defined Routine 


When you use Get SpecificHighLevelEvent, you supply a filter function so 
that your application can search for a specific event in the high-level event queue 
of your application. 


Filter Function for Searching the High-Level Event Queue 


MyFilter 


DESCRIPTION 
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This section describes the filter function that you can provide to 
Get SpecificHighLevelEvent. For example, you might use a filter 
function to search for a high-level event sent from a specific application. 





When you use Get Speci ficHighLevelEvent to search the high-level event queue 
of your application for a specific event, you supply a pointer to a filter function. 

Get SpecificHighLevelEvent calls your filter function once for each event in the 
high-level event queue until your filter function returns TRUE or the end of the queue 
is reached. Your filter function can examine each event and determine whether that 
event is the desired event. If so, your filter function should return TRUE. 











Here’s how you declare the filter function MyFilter: 


FUNCTION MyFilter (yourDataPtr: Ptr; 
msgBuff: HighLevelEventMsgPtr; 











sender: TargetID): Boolean; 


yourDataPtr 
Specifies the criteria your filter function should use to select a specific 
event. For example, you can specify the yourDataPtr parameter as a 
reference constant to search for a particular event, as a pointer to a target 
ID record to search for a specific sender of an event, or as an event class to 
search for a specific class of event. 


msgBuff Contains a pointer to a record of data type HighLevelEventMsg, which 
provides: the event record for the high-level event and the reference 
constant of the event. The HighLevelEventMsg data type is described 
in “The High-Level Event Message Record” on page 2-82. 

sender Contains the target ID record of the application that sent the event. The 
Target ID data type is described in “The Target ID Record” on page 2-81. 


Your filter function can compare the contents of the yourDataPtr parameter with the 
contents of the msgBuff and sender parameters. If your filter function finds a match, it 
can call AcceptHighLevelEvent, if necessary, and your filter function should return 
TRUE. If your filter function does not find a match, it should return FALSE. 
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For information about how to specify your filter function to the 
Get SpecificHighLevelEvent function, see page 2-92. 





This section explains the structure of a 'SIZE' resource and the meaning of each of its 
fields. You are responsible for creating the information in this resource. 


The Size Resource 


Every application executing in System 7, as well as every application executing under 
MultiFinder, should contain a size ('SIZE') resource. One of the principal functions 
of the 'SIZE' resource is to inform the Operating System about the memory size 
requirements for the application so that the Operating System can set up an 
appropriately sized partition for the application. The 'SIZE' resource is also used to 
indicate certain scheduling options to the Operating System, such as whether the 
application can accept suspend and resume events. The 'SIZE' resource in System 7 
contains additional information indicating whether the application is 32-bit clean, 
whether it supports stationery documents, whether it uses TextEdit’s inline input 
services, whether the application wishes to receive notification of the termination of 
any applications it has launched, and whether the application wishes to receive high- 
level events. 














A 'SIZE" resource consists of a 16-bit flags field followed by two 32-bit size fields. The 
flags field specifies operating characteristics of the application, and the size fields 
indicate the minimum and preferred partition sizes for the application. The minimum 
partition size is the actual limit below which your application will not run. The preferred 
partition size is the memory size at which your application can run most effectively and 
which the Operating System attempts to secure upon launching the application. If that 
amount of memory is unavailable, the application is placed into the largest contiguous 
block available, provided that it is larger than the specified minimum size. 


Note 

If the amount of available memory is between the minimum and the 
preferred sizes, the Finder displays a dialog box asking if the user wants 
to run the application using the amount of memory available. If your 
application does not have a 'SIZE" resource, it is assigned a default 
partition size of 512 KB and the Process Manager uses a default value 

of FALSE for all specifications normally defined by constants in the 
flags field. 








When you define a 'SIZE' resource, you should give it a resource ID of —-1. A user can 
modify the preferred size in the Finder’s information window for your application. If the 
user does alter the preferred partition size, the Operating System creates a new 'SIZE' 
resource having resource ID 0. The Process Manager also creates anew 'SIZE' resource 
when the user modifies any of the other settings in the resource. 
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type 'SIZE' 
boolean 
boolean 


boolean 
boolean 


boolean 


boolean 


boolean 


boolean 


boolean 


boolean 


boolean 


boolean 


boolean 
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In system software version 7.1 the user can also modify the minimum size in the Finder’s 
information window for your application. In version 7.1, if the user alters either the 
minimum or the preferred partition size, the Operating System creates two new 'SIZE' 
resources, one with resource ID 0 and one with resource ID 1. 


At application launch time, the Process Manager looks for a 'SIZE"' resource with ID 0 
for the preferred partition size; if this resource is not found, it uses your original 'SIZE' 
resource with ID -1. In version 7.1, the Process Manager looks for a 'SIZE"' resource 
with ID 0 for the preferred size and looks for a 'SIZE' resource with ID 1 for the 
minimum size; if these resources are not found, it uses your original 'SIZE"' resource 
with ID -1. 


Listing 2-19 shows the structure of the 'SIZE" resource in Rez format. See Listing 2-4 in 
“Creating a Size Resource,” beginning on page 2-30 for a sample 'SIZE' resource for 
an application. 


Listing 2-19 A Rez template fora 'SIZE' resource 


{ 


reserved; /*reserved*/ 





ignoreSuspendResumeEvents, /*ignores suspend-resume events*/ 


acceptSuspendResumeEvents; /*accepts suspend-resume events*/ 
reserved; /*reserved*/ 


cannotBackground, /*can't use background null events*/ 





canBackground; /*can use background null events*/ 


needsActivateOnFGSwitch, 


doesActivateOnFGSwitch; 


backgroundAndForeground, 
onlyBackground; 
dontGetFrontClicks, 


getFrontClicks; 


ignoreAppDiedEvents, 
acceptAppDiedEvents; 
not32BitCompatible, 
is32BitCompatible; 
notHighLevelEventAware, 





isHighLevelEventAware; 
onlyLocalHLEvents, 
localAndRemoteHLEvents; 
notStationeryAware, 
isStationeryAware; 
dontUseTextEditServices, 
useTextEditServices; 
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/*needs activate event following */ 
/* major switch*/ 

/*activates own windows in */ 

/* response to OS events*/ 

/*app has a user interface*/ 
/*app has no user interface*/ 
/*don’t return mouse events */ 

/* in front window on resume*/ 
/*do return mouse events */ 

/* in front window on resume*/ 
/*applications use this*/ 

/*app launchers use this*/ 
/*works with 24-bit addr*/ 
/*works with 24- or 32-bit addr*/ 
/*can't use high-level events*/ 
/*can use high-level events*/ 
/*only local high-level events*/ 
/*also remote high-level events*/ 
/*can't use stationery documents*/ 
/*can use stationery documents*/ 
/*can't use inline services*/ 


/*can use inline services*/ 


}; 


boolean 
boolean 
boolean 


unsigned 
unsigned 
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reserved; 
reserved; 


reserved; 


longint; 
longint; 


/*reserved*/ 

/*reserved*/ 

/*reserved*/ 

/*memory sizes are in bytes*/ 
/*preferred memory size*/ 
/*minimum memory size*/ 


The nonreserved bits in the flags field have the following meanings: 


Flag descriptions 


accept SuspendResumeEvents 





canBackground 


When set, indicates that your application can process suspend and 
resume events (which the Operating System sends to your 
application before sending it into the background or when bringing 
it into the foreground). 


Note 

If you set the accept SuspendResumeEvents flag, you should 
also set the doesActivateOnFGSwitch flag. 

When set, indicates that your application wants to receive null 
event processing time while in the background. If your application 
has nothing to do in the background, you should not set this flag. 


doesActivateOnFGSwitch 


onlyBackground 


getFrontClicks 


When set, indicates that your application takes responsibility for 
activating and deactivating any windows in response to a suspend 
or resume event. If the accept SuspendResumeEvents flag is set, 
if the doesActivateOnFGSwitch flag is not set, and if your 
application is suspended, then your application receives an activate 
event following the suspend event. However, if you set the 
doesActivateOnFGSwitch flag, then your application won't 
receive activate events associated with operating-system events, 
and you must take care of activation and deactivation when it 
receives the corresponding suspend or resume event. This means 
that if a window of your application is frontmost, you should treat 
a suspend event as though a deactivate event were received as 

well (assuming that both the doesActivateOnFGSwitch and 
accept SuspendResumeEvents flags are set). For example, you 
should hide scroll bars, hide any caret, and unhighlight any selected 
text if your application moves to the background. If you do not set 
this flag, the Process Manager creates an offscreen window to force 
the activate and deactivate events to occur. 


When set, indicates that your application runs only in the back- 
ground. Usually this is because it does not have a user interface 
and cannot run in the foreground. 


When set, indicates that your application is to receive the 
mouse-down and mouse-up events that are used to bring your 
application into the foreground when the user clicks in your 
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application’s frontmost window. Typically, the user simply wants to 
bring your application into the foreground, so it is usually not 
desirable to receive the mouse events (which would probably move 
the insertion point or start drawing immediately, depending on the 
application). The Finder is one application, however, that has the 
getFrontClicks flag set. 


When the user clicks in the front window of your application and 
causes a foreground switch, your application receives a resume 
event. Your application should activate its front window in 
response to the resume event. In this case if your application’s 
getFrontClicks flag is not set, your application does not receive 
the associated mouse event that caused the foreground switch. If 
your application’s getFrontClicks flag is set, your application 
does receive the associated mouse event. 


Your application always receives the associated mouse event when 
the user clicks in one of your application’s windows other than the 
front window and causes a foreground switch. 


When your application receives a mouse-down event in System 7, 
your application can examine bit 0 of the modifiers field of the 
event record to determine if the mouse-down event caused a 
foreground switch. This information can be especially useful if your 
application sets its getFrontClicks flag. For example, your 
application can examine bit 0 to determine whether to process the 
mouse-down event (probably depending on whether the clicked 
item was visible before the foreground switch). 





acceptAppDiedEvents 
When set, indicates that your application is to be notified whenever 
an application launched by your application terminates or crashes. 
If the Process Manager is available, your application receives this 
information as an Apple event, the Application Died event. See the 
chapter “Process Manager” chapter in Inside Macintosh: Processes for 
more information about launching applications and receiving 
Application Died events. 


Note 

Some early versions of MultiFinder do not send application-died 
events, and your application should not depend on receiving them 
if it is running in System 6. These events are provided primarily for 
use by debuggers. @ 


is32BitCompatible 
When set, indicates that your application can be run with the 32-bit 
Memory Manager. You should not set this flag unless you have 
thoroughly tested your application on a 32-bit system (such as 
a Macintosh IIci computer running System 7 in 32-bit mode or 
under A/UX). 


isHighLevelEventAware 
When set, indicates that your application can send and receive 
high-level events. If this flag is not set, the Event Manager does 
not give your application high-level events when you call 
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WaitNextEvent. There is no way to mask out specific types of 
high-level events; if this flag is set, your application receives all 
types of high-level events sent to your application. 


Your application must support the four required Apple events if 
you set the isHighLevelEventAware flag. See Inside Macintosh: 
Interapplication Communication for information that describes how 
to respond to the four required Apple events. 





localAndRemoteHLEvents 
When set, indicates that your application is to be visible to 
applications running on other computers on a network (in addition 
to applications running on the local computer). If this flag is not 
set, your application does not receive high-level events across 
a network. 


isStationeryAware 
When set, indicates that your application can recognize stationery 
documents. If this flag is not set and the user opens a stationery 
document, the Finder duplicates the document and prompts the 
user for a name for the duplicate document. For information about 
how your application can use stationery documents, see the chapter 
“Finder Interface” in this book. 





useTextEditServices 
When set, indicates that your application can use the inline text 
services provided by TextEdit. See Inside Macintosh: Text for 
information about the inline input capabilities of TextEdit. 


The numbers you specify as your application’s preferred and minimum memory sizes 
depend on the particular memory requirements of your application. Your application’s 
memory requirements depend on the size of your application’s static heap, dynamic 
heap, A5 world, and stack. (See “Introduction to Memory Management” in Inside 
Macintosh: Memory for complete details about these areas of your application’s partition.) 


The static heap size includes objects that are always present during the execution of the 
application—for example, code segments, Toolbox data structures for window records, 
and so on. 


Dynamic heap requirements depend on how many objects are created on a per- 
document basis (which may vary in size proportionally with the document itself) 
and the number of objects that are required for specific commands or functions. 


The size of the A5 world depends on the amount of global data and the number of 
intersegment jumps the application contains. 


Finally, the stack contains variables, return addresses, and temporary information. The 
application stack size varies among computers, so you should base your values for the 
stack size according to the stack size required on a Macintosh Plus (8 KB). The Process 
Manager automatically adjusts your requested amount of memory to compensate for the 
different stack sizes on different machines. For example, if you request 512 KB, more 
stack space (approximately 16 KB) will be allocated on machines with larger default 
stack sizes. 
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Summary of the Event Manager 


Pascal Summary 


Constants 


CONST {event codes} 


nullEvent 





mouseDown 


mouseUp 


keyDown 


keyUp 


autoKey 


updateEvt 


di 


skEvt 





activateEvt 


OSs 





Evt 





kHighLevelEvent 


{event masks} 


everyEvent 


mDownMask 


mUpMask 


keyDownMask 


keyUpMask 


autoKeyMask 


updateMask 


di 


skMask 


activMask 





highLevelEventMask 


osMask 


eT Ty 


POAT A OF WN FO 


Ol xe 
~ 


i) 
Ww 
~e 


64; 
128; 
256; 
1024; 
—32768; 


{no other pending events} 
{mouse button pressed} 
{mouse button released} 
{key pressed} 

{key released} 

{key repeatedly held down} 
{window needs updating} 





{disk inserted} 
{activate/deactivate window} 
{operating-system events } 

{ (suspend, resume, mouse-moved) } 
{high-level events } 


{ (includes Apple events) } 


{every event} 


{mouse-down event (bit 1)} 
{mouse-up event (bit 2) } 
{key-down event (bit 3) } 
{key-up event (bit 4) } 
{auto-key event (bit 5) } 
{update event (bit 6) } 
{disk-inserted event (bit 7) } 
{activate event (bit 8) } 
{high-level event (bit 10) } 
{operating-system event (bit 15) } 


{message codes for operating-system events} 


suspendResumeMessage 


mo 


OSs 
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useMovedMessage 





EvtMessageMask 


$01; 
SFA; 


{suspend or resume event} 


{mouse-moved event} 


SFF000000; {can use to extract msg code} 
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{flags for suspend and resume events} 


resumeFlag = hy {resume event} 


convertClipboardFlag 


2a {Clipboard conversion } 


{ required} 


{event message masks for keyboard events} 





charCodeMask= SOOOOOOFF; {use to get character code} 
keyCodeMask = SOOOOFFOO0; {use to get key code} 
adbAddrMask = SOOFF0O000; {ADB address for ADB keyboard} 


{constants corresponding to bits in the modifiers field of event} 


activeFlag = 1; {bit 0 of low byte--valid only for } 


{ activate and mouse-moved events} 


btnState = 128; {bit 7 of low byte is 
cmdKey = 256; {bit 0 of high byte} 
shiftKey = 512; {bit 1 of high byte} 
alphaLock = 1024; {bit 2 of high byte} 
optionkey = 2048; {bit 3 of high byte} 
controlKey = 4096; {bit 4 of high byte} 


{high-level event posting options} 


mouse button state} 


nAttnMsg = $00000001; {give this message priority} 
priorityMask = SOOOOO0FF; {mask for priority options} 
nReturnReceipt = $00000200; {return receipt requested} 
systemOptionsMask = SOO0000F00; 

receiverIDisTargetID = $00005000; {ID is port name & location} 
receiverIDisSessionID = $00006000; {ID is PPC session ref number} 
receiverIDisSignature = $00007000; {ID is creator signature} 
receiverIDisPSN = $00008000; {ID is process serial number} 
receiverIDMask = $SO0O000F000; 


{class and ID values for return receipt} 
HighLevelEventMsgClass = 'Jjaym'; {event 
rtrnReceiptMsgID = -“rtren" 7 {event 


{modifiers values in return receipt} 


class of return receipt} 
ID of return receipt} 


msgWasNotAccepted = 0; {recipient did not accept } 


{ the message} 


msgWasFullyAccepted = 1; {recipient accepted the} 


{ entire message} 


msgWasPartiallyAccepted = 2; {recipient did not accept } 


{ the entire message} 
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Data Types 
TYPE 
EventRecord = 
RECORD 
what: Integer; 
message: LongInt; 
when: LongInt; 
where: Point; 
modifiers: Integer; 
END; 


KeyMap = PACKED ARRAY [0 


{event code} 

{event message} 
{ticks since startup} 
{mouse location} 
{modifier flags} 


..127] OF Boolean; {records state of keyboard} 


TargetID = 

RECORD 
sessionID: LongInt; {session reference number (not } 

{ used if posting an event) } 

name: PPCPortRec; {port name} 
location: LocationNameRec; {location name} 
recvrName: PPCPortRec; {reserved} 

END; 

TargetIDPtr = “TargetID; {pointer to a target ID record} 

TargetIDHdl = “TargetIDPtr; {handle to a target ID record} 

HighLevelEventMsg = 

RECORD 
HighLevelEventMsgHeaderLength: Integer; {reserved} 
version: Integer; {reserved} 
reservedl: LongInt; {reserved} 
theMsgEvent: EventRecord; {event record} 
userRefCon: LongInt; {reference constant} 
postingOptions: LongInt; {reserved} 
msgLength: LongInt; {reserved} 

END; 

HighLevelEventMsgPtr = *HighLevelEventMsg; 


HighLevelEventMsgHdl 


“HighLevelEventMsgPtr; 


GetSpecificFilterProcPtr = ProcPtr; 
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EvQE1 = {event queue entry} 
RECORD 
qhLink: QElemPtr; {next queue entry} 
qType: Integer; {queue type (ORD (evType) ) } 
evtQWhat: Integer; {event code} 
evtQMessage: LongInt; {event message} 
evtQWhen: LongIint; {ticks since startup} 
evtQWhere: Point; {mouse location} 
evtQModifiers: Integer; {modifier flags} 
END; 
EvQE1Ptr = “EvQE1; 
Event Manager Routines 
Receiving Events 
FUNCTION WaitNextEvent (eventMask: Integer; VAR theEvent: EventRecord; 
sleep: LongInt; mouseRgn: RgnHandle): Boolean; 
FUNCTION EventAvail (eventMask: Integer; VAR theEvent: EventRecord) 
Boolean; 
FUNCTION GetNextEvent (eventMask: Integer; VAR theEvent: EventRecord) 
Boolean; 
FUNCTION AcceptHighLevelEvent 
(VAR sender: TargetID; VAR msgRefcon: LongInt; 
msgBuff: Ptr; VAR msgLen: LongInt): OSErr; 
FUNCTION GetSpecificHighLevelEvent 
(aFilter: GetSpecificFilterProcPtr; 
yourDataPtr: UNIV Ptr; VAR err: OSErr) 
Boolean; 
PROCEDURE FlushEvents (whichMask: Integer; stopMask: Integer) ; 
PROCEDURE SystemClick (theEvent: EventRecord; theWindow: WindowPtr); 
PROCEDURE SystemTask; 
FUNCTION SystemEvent (theEvent: EventRecord): Boolean; 
FUNCTION GetOSEvent (mask: Integer; VAR theEvent: EventRecord) 
Boolean; 
FUNCTION OSEventAvail (mask: Integer; VAR theEvent: EventRecord) 
Boolean; 
PROCEDURE SetEventMask (theMask: Integer); 
FUNCTION GetEvQHdr QHdrPtr; 
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Sending Events 


FUNCTION PostHighLevelEvent (theEvent: EventRecord; receiverID: Ptr; 
msgRefcon: LongInt; msgBuff: Ptr; 
msgLen: LongInt; postingOptions: LongInt) 
OSErr; 





FUNCTION PPostEvent (eventCode: Integer; eventMsg: LongInt; 
VAR gEl: EvQE1Ptr): OSErr; 























FUNCTION PostEvent (eventNum: Integer; eventMsg: LongInt): OSErr; 


Converting Process Serial Numbers and Port Names 


FUNCTION GetProcessSerialNumberFromPortName 
(portName: PPCPortRec; 
VAR PSN: ProcessSerialNumber): OSErr; 


FUNCTION GetPortNameFromProcessSerialNumber 
(VAR portName: PPCPortRec; 
PSN: ProcessSerialNumber): OSErr; 














Reading the Mouse 

PROCEDURE GetMouse (VAR mouseLoc: Point); 
FUNCTION Button : Boolean; 

FUNCTION StillDown : Boolean; 

FUNCTION WaitMouseUp : Boolean; 


Reading the Keyboard 





PROCEDURE GetKeys (VAR theKeys: KeyMap) ; 











{the KeyTranslate function is also available as the KeyTrans function} 





FUNCTION KeyTranslate (transData: Ptr; keycode: Integer; 
VAR state: LongInt): LongInt; 


Getting Timing Information 


FUNCTION TickCount : LongInt; 
FUNCTION GetDb1Time : LongInt; 
FUNCTION GetCaretTime : LongInt; 


Application-Defined Routine 


Filter Function for Searching the High-Level Event Queue 


FUNCTION MyFilter (yourDataPtr: Ptr; 
msgBuff: HighLevelEventMsgPtr; 
sender: TargetID): Boolean; 
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C Summary 


Constants 


enum { 


hi 


enum { 


/*event codes*/ 





nullEvent 
mouseDown 
mouseUp 
keyDown 
keyUp 
autoKey 





updateEvt 
diskEvt 
activateEvt 
osEvt 


/*event masks*/ 
mDownMask 
mUpMask 
keyDownMask 
keyUpMask 
autoKeyMask 
updateMask 
diskMask 
activMask 
highLevelEventMask 
osMask 


everyEvent 





x x x 


x 


x x x 


| 
FON A OB WNHEHE O 
s 


oes 
x 


/* 


ll 
| 
WwW 
NO 
~j 
[o> 
© 


= -1, 


/*no other pending events*/ 
/*mouse button pressed*/ 
/*mouse button released*/ 
/*key pressed*/ 

/*key released*/ 





(suspend, 


/*key repeatedly held down*/ 
/*window needs updating*/ 
/*disk inserted*/ 
/*activate/deactivate window*/ 
/*operating-system events */ 


/*mouse-down 
/*mouse-up 
/*key-down 
/*key-up 
/*auto-key 
/*update 
/*disk-inserted 
/*activate 
/*high-level 


/*operating-system 


/*every event*/ 


/*event message masks for keyboard events*/ 


charCodeMask 
keyCodeMask 
adbAddrMask 
osEvtMessageMask 


OxO000000FF, 
OxO0000FFOO, 
Ox00FFOO00, 
OxFFO000000, 
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resume, mouse-moved) */ 


Pr oA A oO BP WN FP 


/*use to get character code*/ 


/*use to get key code*/ 





/*ADB address if ADB keyboard*/ 
/*can use to extract msg code*/ 
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}; 


enum { 


}; 
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/*message codes for operating-system events*/ 





mouseMovedMessage = OxFA, /*mouse-moved event*/ 
suspendResumeMessage = 0x01, /*suspend or resume event*/ 
/*flags for suspend and resume events*/ 

resumeFlag = 1, /*resume event*/ 
convertClipboardFlag = 2, /*Clipboard conversion */ 


/* rvequired*/ 


/*constants corresponding to bits in the modifiers field of event*/ 


activeFlag = 1, /*bit 0 of low byte--valid only for */ 

/* activate and mouse-moved events*/ 
btnState = 128, /*bit 7 of low byte is mouse button state*/ 
cmdKey = 256, /*bit 0 of high byte*/ 
shiftKey = 512, /*bit 1 of high byte*/ 
alphaLock = 1024, /*bit 2 of high byte*/ 
optionKey = 2048, /*bit 3 of high byte*/ 
controlKey = 4096 /*bit 4 of high byte*/ 
kHighLevelEvent = 23, /*event code for high-level events */ 


/* (includes Apple events) */ 


/*high-level event posting options*/ 


receiverIDMask = 0x0000F000, /*mask for receiver ID bits*/ 
receiverIDisPSN = 0x00008000, /*ID is proc serial number*/ 
receiverIDisSignature = 0x00007000, /*ID is creator signature*/ 
receiverIDisSessionID = 0x00006000, /*ID is session ref number*/ 
receiverIDisTargetID = 0x00005000, /*ID is port name & location*/ 
systemOptionsMask = 0x00000F00, 

nReturnReceipt = 0x00000200, /*return receipt requested*/ 
priorityMask = OxOO00000FF, /*mask for priority options*/ 
nAttnMsg = 0x00000001, /*give this message priority*/ 


/*class and ID values for return receipt*/ 
#define HighLevelEventMsgClass 'jaym' 
#define rtrnReceiptMsgID 'rtrn' 


/*modifiers values in return receipt*/ 
msgWasPartiallyAccepted = 2, 
msgqwasFullyAccepted = 1, 
msgWasNotAccepted = 0 
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Data Types 


struct EventRecord { 


short what; 

long message; 
long when; 
Point where; 
short modifiers; 


hi 


code*/ 


message*/ 


/*event 
/*event 
/*ticks 


/*mouse 


since startup*/ 
location*/ 
/*modifier flags*/ 


typedef struct EventRecord EventRecord; 


typedef long KeyMap[4]; 


struct TargetID { 
long 


PPCPortRec 
LocationNameRec 
PPCPortRec 

}; 


/*records state of keyboard*/ 


sessionID; /*session reference number (not */ 
/* used if posting an event) */ 

name; /*port name*/ 

location; /*location name*/ 

recvrName; /*reserved*/ 


typedef struct TargetID TargetID; 


typedef TargetID *TargetIDPtr, 


**TargetIDHdl; 


struct HighLevelEventMsg { 


unsigned short 
unsigned short 
unsigned long 
EventRecord 

unsigned long 
unsigned long 
unsigned long 

}; 


HighLevelEventMsgHeaderLength; 


/*reserved*/ 


version; /*reserved*/ 
reservedl; /*reserved*/ 
theMsgEvent; /*event record*/ 
userRefCon; /*ref constant*/ 
postingOptions; /*reserved*/ 
msgLength; /*reserved*/ 


typedef struct HighLevelEventMsg HighLevelEventMsg; 


typedef HighLevelEventMsg *HighLevelEventMsgPtr, 


struct EvQE1 { 


/*event queue entry*/ 


**HighLevelEventMsgHdl; 





QElemPtr qLink; /*next queue entry*/ 
short qType; /*queue type (evType) */ 
short evtQWhat; /*event code*/ 

long evtQMessage; /*event message*/ 

long evtQWhen; /*ticks since startup*/ 
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Point evtQWhere; /*mouse location*/ 
short evtQModifiers; /*modifier flags*/ 
}; 
typedef struct EvQE1 EvQE1; 
typedef EvQE1 *EvQE1Ptr; 


typedef pascal Boolean (*GetSpecificFilterProcPtr) 
(void *yourDataPtr, 


HighLevelEventMsgPtr msgBuff, 
const TargetID *sender) ; 


Event Manager Routines 


Receiving Events 





pascal Boolean WaitNextEvent (short eventMask, EventRecord *theEvent, 





unsigned long sleep, RgnHandle mouseRgn) ; 
pascal Boolean EventAvail (short eventMask, EventRecord *theEvent) ; 


pascal Boolean GetNextEvent (short eventMask, EventRecord *theEvent) ; 











pascal OSErr AcceptHighLevelEvent 
(TargetID *sender, unsigned long *msgRefcon, 
Ptr msgBuff, unsigned long *msgLen) ; 





pascal Boolean GetSpecificHighLevelEvent 
(GetSpecificFilterProcPtr aFilter, 
void *yourDataPtr, OSErr *err); 


pascal void FlushEvents (short whichMask, short stopMask); 


pascal void SystemClick (const EventRecord *theEvent, 
WindowPtr theWindow) ; 


pascal void SystemTask (void) ; 
pascal Boolean SystemEvent (const EventRecord *theEvent) ; 
pascal Boolean GetOSEvent (short mask, EventRecord *theEvent) ; 





pascal Boolean OSEventAvail (short mask, EventRecord *theEvent) ; 
pascal void SetEventMask (short theMask) ; 
#define GetEvQHdr () ((QHdrPtr) 0x014A) 


Sending Events 


pascal OSErr PostHighLevelEvent 
(const EventRecord *theEvent, 
unsigned long receiverID, 





unsigned long msgRefcon, Ptr msgBuff, 
unsigned long msgLen, 
unsigned long postingOptions) ; 
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pascal OSErr PPostEvent (short eventCode, long eventMsg, EvQE1Ptr *q 











pascal OSErr PostEvent (short eventNum, long eventMsg) ; 


Converting Process Serial Numbers and Port Names 





pascal OSErr GetPortNameFromProcessSerialNumber 
(PPCPortPtr portName, 
const ProcessSerialNumberPtr pPSN); 
pascal OSErr GetProcessSerialNumberFromPortName 
(const PPCPortPtr portName, 
ProcessSerialNumberPtr pPSN); 


Reading the Mouse 

pascal void GetMouse (Point *mouseLoc) ; 
pascal Boolean Button (void) ; 

pascal Boolean StillDown (void) ; 

pascal Boolean WaitMouseUp (void) ; 


Reading the Keyboard 


pascal void GetKeys (KeyMap theKeys) ; 
{the KeyTranslate function is also available as the KeyTrans function} 


pascal long KeyTranslate (const void *transData, short keycode, 
long *state); 


Getting Timing Information 


pascal unsigned long TickCount 


(void) ; 
#define GetDblTime () (* (unsigned long*) 0x02F0) 
#define GetCaretTime () (* (unsigned long*) 0x02F4) 





Application-Defined Routine 


Filter Function for Searching the High-Level Event Queue 


pascal Boolean MyFilter (void *yourDataPtr, 





HighLevelEventMsgPtr msgBuff, 
const TargetID *sender) ; 
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Assembly-Language Summary 


Data Structures 


Event Data Structure 


0 what 

2 message 

6 when 

10 where 

14 modifiers 


Target ID Data Structure 


0 sessionID 

4 name 

72 location 
106 recvrName 


word event code 

long event message 

long ticks since startup 

long mouse location 

word modifier flags 

long session reference number (not used if posting event) 
68 bytes port name (specified ina PPCPortRec data structure) 
34 bytes location name (specified in a Locat ionNameRec) 

68 bytes reserved 


High-Level Event Message Data Structure 


0 HighLevell 








EventMsgHeaderLength 


word reserved 
2 version word reserved 
4 reservedl long reserved 
8 theMsgEvent 16 bytes event record 
22 userRefCon long reference constant 
26 postingOptions long reserved 
30 msgLength long reserved 


Event Queue Header Data Structure 


0 qhink long 
4 qType word 
6 evtQWhat word 
8 evtQMessage long 
12 evtQWhen long 
16 evtQWhere long 
20 evtQModifiers word 


Trap Macros 


next queue entry 
queue type 

event code 

event message 
ticks since startup 
mouse location 
modifier flags 


Trap Macros Requiring Routine Selectors 








_OSDispatch 

Selector Routine 

$0033 AcceptHighLevelEvent 
$0034 PostHighLevelEvent 
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Selector Routine 

$0035 GetProcessSerialNumberFromPortName 
$0045 Get SpecificHighLevelEvent 

$0046 GetPortNameFromProcessSerialNumber 


Trap Macros Requiring Register Setup 


Trap macro name 





_FlushEvents 





_GetOSEvent 


_OSEventAvail 





_PostEvent 


Global Variables 


CaretTime 


Registers on entry Registers on exit 
DO: event mask (low-order word) DO: 0 if all events were removed from the 
stop mask (high-order word) queue, or the event code of the event 
that stopped the search (low-order 
word) 


AO: address of event record 

DO: event mask (low-order word) D0: 0 if GetOSEvent returns any event 
other than a null event, or —1 if it 
returns a null event (low-order byte) 


AO: address of event record 

DO: event mask (low-order word) D0: 0 if OSEventAvail returns any event 
other than a null event, or —1 if it 
returns a null event (low-order byte) 





AO: event code (low-order word) 
DO: event message (long word) DO: result code (low-order word) 


The suggested difference in ticks that should exist between blinks of the 


DoubleTime 


EventQueue 


KeyRepThresh 


KeyThresh 


ScrDmpEnable 


SEvtEnb 


SysEvtMask 
Ticks 


caret in editable text. 


The suggested maximum difference in ticks that should exist between the 
time of a mouse-up event and a mouse-down event for your application to 
consider those two mouse events a double click. 

The header of the event queue. 

The value of the auto-key rate (the amount of time, in ticks, that must elapse 
before the Event Manager generates a subsequent auto-key event). 


The value of the auto-key threshold (the amount of time, in ticks, that must 
elapse before the Event Manager generates an auto-key event). 


A byte that, if set to 0, disables the Event Manager’s processing of 
Command-Shift-number key combinations with numbers 3 through 9. 


A byte that, if set to 0, causes the SystemEvent function to always return 
FALSE. 


The system event mask of the current application. 


A long integer that indicates the current number of ticks since the system 
last started up. 
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Result Codes 








noErr 0 
procNotFound -—600 
bufferIsSmall —607 
noOutstandingHLE 608 
connectionInvalid —609 
noUserInteractionAllowed -610 
noPortErr -903 
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No error 

No eligible process with specified process serial number 
Buffer is too small 

No outstanding high-level event 

Connection is invalid 

Cannot interact directly with user 

Invalid port name 
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Menu Manager 


You can use the Menu Manager to create and manage the menus in your application. 
Menus allow the user to view or choose from a list of choices and commands that your 
application provides. 


All Macintosh applications should provide these standard menus: the Apple menu, the 
File menu, and the Edit menu. If you include an Apple menu as a menu of your 
application, the Menu Manager automatically adds the Help and Application menus to 
your application’s menu bar; it adds the Keyboard menu if more than one keyboard 
layout or input method is installed. 


Menus are typically stored as resources. This chapter describes the menu-related 
resources. See the chapter “Introduction to the Macintosh Toolbox” in this book for 
general information on resources and see the chapter “Resource Manager” in Inside 
Macintosh: More Macintosh Toolbox for information on Resource Manager routines. 
See Macintosh Human Interface Guidelines for additional examples of menus that 
incorporate many principles of user interface design. Inside Macintosh: Text contains 
further information on localizing your application for worldwide markets. 


You can choose to provide help balloons for your application’s menus. See the chapter 
“Help Manager” in Inside Macintosh: More Macintosh Toolbox for additional details on 
providing help balloons for your application’s menus. 


You often present a dialog box to the user as a result of the user’s choice of a menu 
command that requires additional information before you can perform the command. 
See the chapter “Dialog Manager” later in this book for information on creating dialog 
boxes in your application. 


For additional information on processing events, see the chapter “Event Manager” 
earlier in this book. 


This chapter provides an introduction to menus and the menu bar, and it then describes 
m various types of menus your application can use 

m standard menus 

m how to store menus as resources 

m how to create menus 

m how to create a menu bar 

m how to change characteristics of menu items 


m= how to add items to a menu 


Introduction to Menus 


A menu is a user interface element you can use in your application to allow the user to 
view or choose an item from a list of choices and commands that your application 
provides. Menus can appear in several different forms: pull-down menus, hierarchical 
menus, and pop-up menus. 
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A pull-down menu is identified by a menu title (a word or an icon) in the menu bar. 
Your application can use pull-down menus in the menu bar to allow users to choose a 
command or perform an action on a selected object. A pop-up menu is a menu that does 
not appear in the menu bar, but appears elsewhere on the screen when the user presses 
the mouse button while the cursor is in a particular place. Pop-up menus are most often 
accessed from a dialog box. Your application can use pop-up menus to let the user select 
one choice from a list of many or to set a specific value. A submenu refers to a menu that 
is attached to another menu. A menu to which a submenu is attached is referred to as a 
hierarchical menu. 


Figure 3-1 shows examples of a pull-down menu, a submenu, and a pop-up menu. 


Figure 3-1 A pull-down menu, a submenu, and a pop-up menu 
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The standard menu bar extends across the top of the startup screen and contains the title 
of each available pull-down menu. Your application’s menu bar should always provide 
at least the Apple menu, the File menu, and the Edit menu. When you insert the Apple 
menu in your application’s menu bar, the Menu Manager automatically adds the Help 
and Application menus to your application’s menu bar. It also adds the Keyboard menu 
if multiple script systems are installed or if a certain bit is set in the 'it1c' resource. 
Your application can include as many other menus as fit on the smallest screen on which 
your application runs, and you should create only as many items as are essential to your 
application. 


If your application uses a menu bar, you should make it always visible and available for 
use. If you do not always wish to display the menu bar (for example, if your application 
allows the user to view a screen presentation), you can give the user the option of 
viewing the presentation on the entire screen without the menu bar showing. However, 
you must provide a way, such as a keyboard equivalent for a command, for the user to 
access the menu bar or to make the menu bar reappear. 


Using menus in your application allows the user to explore many possible choices and 
options without having to choose any particular one. By providing help balloons for 
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your menus, you further allow users to learn about the possible actions or consequences 
of a particular menu choice without having to choose the menu command to find out 
what happens. 


Figure 3-2 shows the SurfWriter application’s menu bar with the Edit menu displayed. 
This application supports the standard Apple, File, and Edit menus; the Help and 
Application menus; and in addition supports two other application-specific menus. 


Figure 3-2 The SurfWriter application’s menu bar with the Edit menu displayed 
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Each menu has a menu title and one or more menu items associated with it. You should 
name each menu so that the title describes or relates to the actions the user can perform 
from that menu. For example, the Edit menu of a typical application contains commands 
that let the user edit the contents of a document. 


Your application can disable any menu. The Menu Manager indicates that a menu is 
disabled by dimming its menu title. (In Figure 3-2, the Colors menu is disabled.) The 
Menu Manager dims all menu items of a disabled menu. The user can still pull down and 
examine the items in a disabled menu, but cannot choose any of the items. 


Your application can also disable individual menu items. The Menu Manager dims the 
appearance of a disabled item and does not highlight it when the user rests the cursor on 
that item. If the user releases the mouse button while the cursor is over a disabled menu 
item, the Menu Manager reports that the user did not choose a menu command. (You can 
determine if this happened, however, by using the MenuChoice function.) 


In Figure 3-2, the Paste command is disabled; the SurfWriter application disables the 
Paste command if the Clipboard is empty. SurfWriter also disables the Publisher Options 
command when the current selection does not contain a publisher or a subscriber. As 
explained in the chapter “Help Manager” in Inside Macintosh: More Macintosh Toolbox, 
your application should provide help balloons for disabled items that describe what the 
item normally does and explain why the item is not available at this time. 
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Note 

Although enabled and disabled are the constants you use in a 
resource file to display or to dim menus and menu items, you shouldn’t 
use these terms in your help balloons or user documentation. Instead 
use the terms menus, menu commands, and menu items for those that are 
enabled, and use the terms not available and dimmed to distinguish those 
that have been disabled. 


The Menu Manager highlights an enabled menu item when the cursor is over it. 
Enabled items do not have a dim appearance and can be chosen by the user. 


Your application specifies whether menu items are enabled or disabled when it first 
defines and creates a menu. You can also disable or enable menu items at any time after 
creating a menu. You should enable a menu item whenever your application allows the 
user to choose the action associated with that item, and you should disable an item 
whenever the user cannot choose that item. For example, if the user selects text and then 
presses the mouse button while the cursor is in the menu bar, you should enable the 
Copy command in the Edit menu. You should disable the Copy command in the Edit 
menu if the user has not selected anything to copy. 


Your application can also specify other characteristics of menu items, such as whether 
the item has a marking character next to its text (for example, a checkmark) or whether 
the item has a keyboard equivalent (for example, Command-C for the Copy command). 
“Menu Items” beginning on page 3-12 describes the characteristics of individual menu 
items in more detail. 


The user typically chooses commands by moving the cursor to the menu bar and 
pressing the mouse button while the cursor is over a menu title. When the user presses 
the mouse button while the cursor is in the menu bar, your application should call the 
MenuSelect function. TheMenuSelect function tracks the mouse, displays and 
removes menus as the user drags the cursor through the menu bar, highlights menu 
titles as the user drags the cursor over them, displays the menu items associated with a 
selected menu, highlights enabled menu items as the user drags through a menu, and 
handles all user activity until the user releases the mouse button. 


The user chooses a menu item by releasing the mouse button while the cursor is over a 

particular enabled menu item. When the user chooses a menu item, the Menu Manager 
briefly blinks the chosen menu item (to confirm the choice) and then removes the menu 
from the display. The Menu Manager leaves the title of the chosen menu highlighted to 

provide feedback to the user. 


The MenuSelect function returns information that allows your application to 
determine which menu item was chosen. Your application then typically responds by 
performing the desired command. When your application completes the requested 
action, your application should unhighlight the menu title, indicating to the user that the 
action is complete. 


The user can move the cursor out of the menu (or menu bar) at any time; the Menu 
Manager displays any currently visible menu as long as the mouse button is pressed. (If 
the cursor is outside of the menu, the Menu Manager removes any highlighting of the 
menu item.) If the user releases the mouse button outside of a menu, the MenuSelect 
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function reports that the user did not choose a menu item, and the Menu Manager 
removes any currently visible menu. Your application should not take any action if the 
user does not choose a menu item. 


Menu and Menu Bar Definition Routines 


The menu definition procedure and menu bar definition function define the general 
appearance and behavior of menus. The Menu Manager uses these routines to display 
and perform basic operations on menus and the menu bar. 


A menu definition procedure performs all the drawing of menu items within a menu. 
When you define a menu, you specify its menu definition procedure. The Menu 
Manager uses the specified menu definition procedure to draw the menu items in a 
menu, determine which item the user chose from a menu, insert scrolling indicators as 
items in a menu, and calculate the menu’s dimensions. 


A menu bar definition function draws the menu bar and performs most of the drawing 
activities related to the display of menus when the user moves the cursor between them. 
Unless you specify otherwise, the Menu Manager uses the standard menu bar definition 
function to manage your application’s menu bar. The Menu Manager uses the standard 
menu bar definition function to draw the menu bar, clear the menu bar, determine 
whether the cursor is in the menu bar or any currently displayed menu, calculate the left 
edges of menu titles, highlight a menu title, invert the entire menu bar, erase the 
background color of a menu and draw the menu’s structure (shadow), and save or 
restore the bits behind a menu. 


Apple provides a standard menu definition procedure and standard menu bar definition 
function. These definition routines are stored as resources in the System file. The 
standard menu definition procedure is the 'MDEF' resource with resource ID 0. The 
standard menu bar definition function is the 'MBDF'' resource with resource ID 0. 








When you define your menus and menu bar, you specify the definition routines that the 
Menu Manager should use when managing them. You'll usually want to use the 
standard definition routines for your application. However, if you need a feature not 
provided by the standard menu definition procedure (for example, if you want to 
include more graphics in your menus), you can choose to write your own menu 
definition procedure. See “Writing Your Own Menu Definition Procedure” beginning on 
page 3-87 for more information. While the Menu Manager does allow you to specify 
your own menu bar definition function, Apple recommends that you use the standard 
menu bar definition function. 


The Menu Bar 


Each application has its own menu bar. The menu bar of an application applies to only 
that application. You usually define a menu bar for your application by providing a 
menu bar ('MBAR') resource that lists the order and resource ID of each menu that 
appears in your menu bar. You define the menu title and the individual characteristics of 
menu items that appear in a menu by providing a menu ('MENU') resource for each 
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menu that appears in your menu bar. You use Menu Manager routines to create the 
menus and menu bar based on these resource definitions. 


Your application can change the enabled state of a menu, add menus to or remove 
menus from its menu bar, or change the characteristics of any menu items. Whenever 
your application changes the enabled state of a menu or the number of menus in its 
menu bar, your application must call the DrawMenuBar procedure to update the menu 
bar’s appearance. 


The menu bar (as defined by the standard menu bar definition function) is white, with a 
height that is tall enough to display menu titles in the height of the system font and 
system font size, and with a black lower border that is one pixel tall. The menu bar is as 
wide as the screen and always appears on the monitor designated by the user as the 
startup screen. (The user selects a startup screen using the Monitors control panel.) The 
menu bar appears at the top of the screen, and nothing except the cursor can appear in 
front of it. Figure 3-3 shows the menu bar of the SurfWriter application. 


Figure 3-3 The menu bar of the SurfWriter application 
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The menu bar helps to indicate the active application. The active application is the one 
whose menu bar is currently showing and whose icon appears as the menu title of the 
Application menu. 


The titles of menus appear in the menu bar. A menu title is a text string (except for the 
Apple, Help, Keyboard, and Application menus, the titles of which contain a small icon). 
Menu titles always appear in the system font and system font size (for Roman scripts, 
the system font is Chicago and the system font size is 12). 


You can insert any number of menu titles in the menu bar; however, less than 10 is 
usually optimum. Keep in mind that not all users have the same size monitor. Design 
your menu bar so that all titles can fit in the menu bar of the smallest screen on which 
your application can run. You should also consider localization issues when designing 
the number of menus that fit in your menu bar—not all menu titles might fit in the menu 
bar once the menu titles are translated. For example, English text often grows 50 percent 
larger when translated to other languages. 


Figure 3-4 shows the SurfWriter application’s menu bar with menu titles that have been 
localized for another script system. 


Figure 3-4 The SurfWriter application’s menu bar localized for another script system 
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Menus 


A menu (as defined by the standard menu definition procedure) is a list of menu items 
arranged vertically and contained in a rectangle. The rectangle is shaded and can extend 
vertically for the length of the screen. If a menu has more items than will fit on the 
screen, the standard menu definition procedure adds a downward-pointing triangular 
indicator to the last item on the screen, and it automatically scrolls through the 
additional items when the user moves the cursor past the last menu item currently 
showing on the screen. When the user begins to scroll through the menu, the standard 
menu definition procedure adds an upward-pointing triangular indicator to the top item 
on the screen to indicate that the user can scroll the menu back to its original position. 


Each menu can have color information associated with it. If you do not define the colors 
for your menus in your application’s menu color information table, the Menu Manager 
uses the default colors for your menus and menu bar. The default colors are black text on 
a white background. In most cases the default colors should meet the needs of your 
application. “The Menu Color Information Table Record” on page 3-98 and “The Menu 
Color Information Table Resource” on page 3-155 give information on how you can 
define colors for your application’s menus. 


Your application’s menus can contain any number of menu items. “Menu Items” 
(the next section) describes the visual variations that you can use when defining your 
menu items. 


You typically define the order and resource IDs of the menus in your application’s menu 
bar in an 'MBAR' resource. You should define your 'MBAR' resource such that the Apple 
menu is the first menu in the menu bar. You should define the next two menus as the File 
and Edit menus, followed by any other menus that your application uses. You do not 
need to define the Keyboard, Help, or Application menus in your 'MBAR" resource; the 
Menu Manager automatically adds them to your application’s menu bar if your 
application calls the GetNewMBar function and your menu bar includes an Apple menu 
or if your application inserts the Apple menu into the current menu list using the 
InsertMenu procedure. 





You define the menu title and characteristics of each individual menu item ina 'MENU' 
resource. “Creating a Menu Resource” on page 3-43 describes the 'MENU' resource in 
more detail. 


Pop-up menus do not appear in the menu bar but appear elsewhere on the screen. You 
often use pop-up menus in a dialog box when you want the user to be able to make a 
selection from a large list of choices. For example, rather than displaying the choices 
as a number of radio buttons, you can use a pop-up menu to display the choices at the 
user’s convenience. 


A hierarchical menu refers to either a pull-down or pop-up menu that has a submenu 
attached to it. (However, you should avoid attaching a submenu to a pop-up menu 
whenever possible, as this can make the interface more complex and less intuitive to 
the user.) 
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“Creating a Pop-Up Menu” on page 3-56 gives additional information about pop-up 
menus, and “Creating a Hierarchical Menu” on page 3-53 describes hierarchical menus 
in more detail. 


Menu Items 


A menu item can contain text or can be a line (a divider) separating groups of choices. A 
divider is always dimmed, and it has no other characteristics associated with it. 


Each menu item (other than dividers) can have a number of visual characteristics: 


m Anicon to the left of the menu item’s text. If you define an icon for a menu item, use 
an icon that gives a symbolic representation of the menu item’s meaning or effect. You 
can specify an icon, a small icon, a reduced icon, or a color icon as the icon for a menu 
item; however, items with small or reduced icons cannot have submenus and cannot 
be drawn ina script other than the current system script. 


m A checkmark or other marking character to the left of the menu item’s text (and to the 
left of the item’s icon, if any). Use such a mark if you need to denote the status of the 
menu item or the mode it controls. A menu item can have a mark or a submenu, but 
not both. 


m The symbol for the Command key (3) and another 1-byte character to the right of the 
menu item’s text (referred to as the keyboard equivalent of acommand). Use this if your 
application allows the user to invoke the menu command from the keyboard by 
pressing the Command key and one or more other keys in combination, just as if the 
user had chosen the command from the menu. An item that has a keyboard 
equivalent cannot have a submenu, a small icon, or a reduced icon and cannot be 
drawn in a script other than the current system script. 


m A triangular indicator to the right of the menu item’s text to indicate that the item has 
a submenu. A menu item that has a submenu cannot have a keyboard equivalent, a 
marking character, a small icon, or a reduced icon and cannot be drawn in a script 
other than the current system script. 


m A font style—either plain or one of various other styles—for the menu item’s text. You 
can set the menu item’s style to bold, italic, underline, outline, shadow, or any 
combination of these. 


m The text of the menu item. Choose words for menu items that declare the action that 
occurs when the user chooses the command (usually verbs, such as Print or Save). You 
can also use adjectives if the command changes the attribute of a selected object (for 
example, Bold or Italic). Unless you specify otherwise, the text of menu items appears 
in the script of the system font and system font size (for Roman scripts, the system 
font is Chicago and the system font size is 12 points). If you want a menu item’s text 
to appear in a script other than the current system script, you can specify a script code 
for the text. The Menu Manager draws the item’s text in the script identified by the 
script code if the script for the specified script system is installed. A menu item that is 
drawn in another script cannot have a submenu, small icon, or reduced icon. 


m Three ellipsis points (...) as the last character in the text of the menu item. Use ellipses 
in the text of menu items to indicate that your application displays a dialog box that 
requests more information from the user before executing the command. Do not use 
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ellipses in menu items that display informational dialog boxes that do not require 
additional information from the user. In addition, you should not use ellipses if your 
application displays a confirmation alert after the user chooses a menu command. For 
example, if the user makes changes to a document, then chooses the Close command, 
your application can display a confirmation alert box, asking the user whether the 
document should be saved before closing. This type of command should not contain 
ellipses in its text. 


If your application displays a dialog box requesting more information in response to 
the choice of a menu command, do include ellipses in the menu item’s text. For 
example, the Open command includes ellipses in its text because the user must 
provide additional information: the name of the file to open. When you request more 
information from the user in a dialog box, you should provide an OK button or its 
equivalent in the dialog box that the user can select to perform the command. The 
dialog box should also include a Cancel button or its equivalent so that the user can 
cancel the command. See the chapter “Dialog Manager” in this book for information 
on creating dialog boxes. 


m= A dimmed appearance. When your application disables a menu item, the Menu 
Manager dims the menu item to indicate that the user can’t choose it. Note that the 
Menu Manager dims the entire menu item, including any mark or icon, the menu text, 
and any keyboard equivalent symbol. Divider lines always have a dimmed 
appearance, regardless of whether your application enables them or not. When your 
application disables an entire menu, the Menu Manager dims the menu title and all 
menu items in that menu. 


Figure 3-5 shows two menus with menu items that illustrate many of the characteristics 
that you can use when defining your menu items. 


Figure 3-5 Two menus with various characteristics 
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When the primary line direction is right to left (as is the case for non-Roman script 
systems such as Arabic) the Menu Manager reverses the order of elements in menu 
items. For example, any marking character appears to the far right and any keyboard 
equivalent appears to the far left of the menu item’s text. 
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On a monitor that is set to display only black and white, the Menu Manager displays 
dividers as dotted lines. In all other cases, the Menu Manager displays dividers as 
appropriate, based on the current color table. For example, on a monitor set to display 
4-bit color or greater, the Menu Manager typically displays dividers as gray lines. 


Your menu can contain as many menu items as you wish. However, only the first 

31 menu items can be individually disabled (all menu items past 31 are always enabled 
if the menu is enabled and always disabled if the menu is disabled). If your menu items 
exceed the length of the screen, the user must scroll to view the additional items. Keep 
in mind that the fewer the menu items in a menu, the simpler and clearer the menu is 
for the user. 


Groups of Menu Items 


The menu items in a particular menu should be logically related to the title of the menu 
and grouped to provide greater ease of use and understanding to the user. You should 
separate groups with dividers. 


A menu can contain both commands that perform actions and commands that set 
attributes. You should use a verb or verb phrase to name commands that perform actions 
(for example, Cut, Copy, Paste). You should use an adjective to name commands that set 
attributes of a selected object (for example, Bold, Italic, Underline). You should group 
menu items by their type: verbs (actions) or adjectives (attributes). Create groups within 
each type according to the guidelines described here. 


Group action commands that are logically related but independent; this makes your 
menus easier to read. For example, the Cut, Copy, Paste, Clear, and Select All commands 
in the Edit menu are grouped together; the Create Publisher, Subscribe To, and Publisher 
Options commands are grouped together; and the Show Clipboard command is set 

off by itself. (Figure 3-5 on page 3-13 shows these commands in the Edit menu of a 
typical application.) 


Group attribute commands that are interdependent. You typically group a set 
of commands that set attributes into either a mutually exclusive group or an 
accumulating group. 


Group a set of attribute commands together if only one attribute in the group can be in 
effect at any one time (a mutually exclusive group). Place a checkmark next to the item 
that is currently in effect. If the user chooses a different attribute in the group, move the 
checkmark to the newly chosen attribute. For example, Figure 3-6 shows a Colors menu 
from the SurfWriter application. The colors listed in the Colors menu form a mutually 
exclusive group because only one color can be in effect at any one time. In this example, 
green is the color currently in effect. If the user chooses a different color, such as blue, the 
SurfWriter application uses the Set ItemMark procedure to remove the checkmark from 
the Green command and to place a checkmark next to the Blue command. 
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Figure 3-6 Menu items in a mutually exclusive group 
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You can also group a set of attribute commands together if a number of the attributes in 
the group can be in effect at any one time (an accumulating group). In an accumulating 
group, use checkmarks to indicate that multiple attributes are in effect. In this type 

of group, you also need to provide a command that cancels all the other attributes. For 
example, a Style menu that lets the user choose any combination of font styles should 
also include a Plain Text command that cancels all the other attributes. Figure 3-7 shows 
a Style menu; in this example, the Bold and Outline attributes are both in effect. 


Figure 3-7 Menu items in an accumulating group 
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You can also use a combination of checkmarks and dashes to help indicate the state of 
the user’s content. For example, in a menu that reflects the state of a selection, place a 
checkmark next to an item if the attribute applies to the entire selection; place a dash 
next to an item if the attribute applies to only part of the selection. Figure 3-8 shows a 
Style menu that indicates that the selection contains more than one style. In this figure, 
the Bold attribute applies to the entire selection; the Underline attribute applies to only 
part of the selection. 


Figure 3-8 Use of a checkmark and dash in an accumulating group 
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Your application should adjust its menus appropriately before displaying its menus. 
For example, you should add checkmarks or dashes to items that are attributes as 
necessary, based on the state of the user’s document and according to the type of 
window that is in the front. See “Adjusting the Menus of an Application” on page 3-73 
for more information. 


Another way to show the presence or absence of an attribute is to use a toggled 
command. Use a toggled command if the attribute has two states and you want to allow 
the user to move between the two states using a single menu command. For example, 
your application could provide a Show Borders command when the borders 
surrounding publishers and subscribers are not showing in a document. When the user 
chooses the Show Borders command, your application should show the borders and 
change the menu item to Hide Borders. When the user chooses the Hide Borders 
command, your application should hide the borders surrounding any publishers or 
subscribers and change the menu item to Show Borders. Use a toggled command only 
when the wording of the two versions of the command is not confusing to the user. 
Choose a verb phrase as the text of a toggled command; the text should clearly indicate 
the action your application performs when the user chooses the item. See “Changing the 
Text of an Item” on page 3-59 for further information on providing a toggled command. 


Keyboard Equivalents for Menu Commands 


A menu command can have a keyboard equivalent. The term keyboard equivalent 
refers to a keyboard combination, such as Command-C (3£-C) or any other combination 
of the Command key, another key, and one or more modifier keys, that invokes a 
corresponding menu command when pressed by the user. For example, if your 
application supports the New command in the File menu, your application should 
perform the same action when the user presses Command-N as when the user chooses 
New from the File menu. 


The term Command-key equivalent refers specifically to a keyboard equivalent that the 
user invokes by holding down the Command key and pressing another key (other than a 
modifier key) at the same time. This generates a keyboard event that specifies a 1-byte 
character that your application should pass as a parameter to the MenuKey function. The 
MenuKey function maps the given 1-byte character to the menu item (if any) with that 
Command-key equivalent. 


The Menu Manager provides support for Command-key equivalents. If you define a 
Command-key equivalent for a menu item, the standard menu definition procedure 
draws the Command symbol and the specified 1-byte character to the right of the menu 
item’s text (or to the left of the item’s text if the primary line direction is right to left). 


You detect a Command-key equivalent of a command by examining the modifiers 

field of the event record for a keyboard event. This allows you to determine whether 

the Command key was pressed at the same time as the keyboard event. If so, your 
application typically calls the MenuKey function, passing as a parameter the character 
code that represents the key pressed by the user. The MenuKey function determines if the 
1-byte character matches any of the keyboard equivalents defined for your menu items; 
if so, MenuKey returns this information to your application. Your application can then 
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perform the associated menu command, if any. See the chapter “Event Manager” in this 
book for additional information about the modifiers field of the event record. 


The keyboard layout ('KCHR') resource of some keyboards masks or cancels the effect of 
the Shift key when the Command key is also pressed. For example, with a U.S. keyboard 
layout, when a user presses Command-S, the character code in the message field of the 
event record is $73 (the character code for “s”); when a user presses Command-Shift-S, 
the character code in the message field of the event record is also $73. However, not all 
'KCHR' resources mask the Shift key in this way. 


Furthermore, when your application uses the MenuKey function to process Command- 
key equivalents, MenuKey does not distinguish between uppercase and lowercase 
letters. The MenuKey function takes the 1-byte character passed to it and calls the 
UpperText procedure (which provides localizable uppercase conversion of the 
character). Thus, MenuKey translates any lowercase character to uppercase when 
comparing a keyboard event to keyboard equivalents. If your application must 
distinguish between lowercase and uppercase characters for keyboard equivalents, you 
need to provide your own method for handling such keyboard equivalents. 


The key you specify for a Command-key equivalent must be a 1-byte character and is 
usually a letter (although you can specify 1-byte characters other than letters). For 
consistency and to provide greater support for localizing your application, you should 
always specify any letters for keyboard equivalents in uppercase when you define your 
application’s menu commands. 


If you wish to provide other types of keyboard equivalents in addition to Command-key 
equivalents, your application must take additional steps to support them. If your 
application allows the user to hold down more than one modifier key to invoke a 
keyboard equivalent, your application must provide in the menu item a visual indication 
that represents this keyboard combination. In most cases your application must use its 
own method (other than MenuKey) for mapping the keyboard equivalent to the 
corresponding menu item. 


If you specify a key other than a letter for a Command-key equivalent or use more than 
one modifier key for a keyboard equivalent, you should choose keys and keyboard 
combinations that can be easily localized for other regions. 


If your application uses other keyboard equivalents, you can examine the state of the 
modifier keys and use the KeyTranslate function, if necessary, to help map the 
keyboard equivalent to a particular menu item. See the chapter “Event Manager” in this 
book for information on the KeyTranslate function, and see the discussion of 'KCHR' 
resources in Inside Macintosh: Text for information on how various keyboard 
combinations map to specific character codes. 


One command that isn’t listed in a menu but can be invoked from the keyboard is the 
Command-period (#8-.) or Cancel command. You detect a Command-period command 
in a method similar to the method for detecting other keyboard equivalents—you 
examine the modifiers field of a keyboard event to determine whether the Command 
key was pressed. In this case, however, if the user pressed the period key in addition to 
the Command key, rather than invoking a menu command your application should 
cancel the current operation. 
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You typically define the Command-key equivalents for your application’s menu 
commands when you define the menu commands ina 'MENU' resource. The Menu 
Manager displays the Command-key equivalent for a menu command (if it has one) 
to the right of the menu item’s text (or to the left of the item’s text for right-to-left 
script systems). 


Apple reserves several keyboard equivalents for common commands. You should use 
these keyboard equivalents for commands in the File and Edit menus of your application. 


Table 3-1 show the keyboard equivalents for standard commands. 


Table 3-1 Reserved keyboard equivalents for all systems 
Keys Command Menu 
BEA Select All Edit 
a6-C Copy Edit 
aE-N New File 
3e-O Open... File 
BE-P Print... File 
36-O Quit File 
BES Save File 
3e-V Paste Edit 
3e-W Close File 
BE-X Cut Edit 
SE-Z, Undo Edit 
Note 


You should use the keyboard equivalents Z, X, C, and V for the editing 
commands Undo, Cut, Copy, and Paste in order to provide support for 
editing in desk accessories and dialog boxes. 


Apple also reserves several keyboard equivalents for use with worldwide versions of 
system software, localized keyboards, and keyboard layouts. Table 3-2 shows these 
keyboard equivalents. Your application should not use the keyboard equivalents listed in 
Table 3-2 for its own menu commands. 


See Inside Macintosh: Text for more discussion of handling keyboard equivalents in other 
script systems. 


The key combinations listed in Table 3-1 and Table 3-2 are reserved across all 
applications. Even if your application doesn’t support one of these menu commands, it 
shouldn’t use these keyboard equivalents for another command. This guideline is for the 
user’s benefit. Reserving these key combinations provides guaranteed, predictable 
behavior across all applications. 
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Table 3-2 Reserved keyboard equivalents for worldwide systems 

Keys Action 

#6-Space bar Rotate through enabled script systems 

#6—Option-Space bar Rotate through keyboard layouts or input methods 
within the active script system 

a6—modifier key—Space bar Reserved 

a6-Right arrow Change keyboard layout to the current keyboard 


layout of the Roman script 


a6-Left arrow Change keyboard layout to the current keyboard 
layout of the system script 


Table 3-3 shows other common keyboard equivalents. These keyboard equivalents are 
secondary to the standard keyboard equivalents listed in Table 3-1 and Table 3-2. If your 
application doesn’t support one of the functions in Table 3-3, then you can use the 
equivalent as you wish. 


Table 3-3 Other common keyboard equivalents 
Keys Command Menu 

SE-B Bold Style 

SEF Find File 

#6-G Find Again File 

SE-1 Italic Style 


36-T Plain Text Style 
#6-U ——- Underline Style 


You shouldn’t assign keyboard equivalents to infrequently used menu commands. Only 
add keyboard equivalents for the commands that your users employ most frequently. 


Menus Added Automatically by the Menu Manager 


In System 7, the Menu Manager may add as many as three additional menus to your 
application’s menu bar: the Help menu, the Keyboard menu, and the Application menu. 
These menus provide access to system features such as Balloon Help, keyboard layouts, 
and application switching. All three of these menus have icons as titles and are 
positioned at the right side of the menu bar. (These menus are sometimes referred to as 
the system-handled menus.) 


The Menu Manager automatically inserts these additional menus in your application’s 
current menu list when your application inserts an Apple menu into its menu bar. In this 
case, the Menu Manager always displays the Application menu, displays the Help menu 
if space is available, and displays the Keyboard menu if multiple script systems are 
installed and space is available. The Menu Manager also displays the Keyboard menu if 
the sm£ShowIcon bit is set in the flags byte of the 'it1lc' resource. 
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The Help menu icon or both the Help menu icon and the Keyboard menu icon disappear 
from the menu bar if your application inserts a menu whose title extends into the space 
occupied by one or both of those icons. This allows your application to reclaim any space 
in the menu bar that would have been occupied by one or both of those two menu icons, 
if necessary. However, if your application inserts a menu whose title is long enough to 
overlap space occupied by the Application menu icon, the overlapping portion of that 
title disappears behind the Application menu icon. The Application menu icon is always 
displayed in the menu bar. 


Because the Menu Manager inserts the Help, Keyboard, and Application menus into 
your application’s current menu bar, you should not make any assumptions about the 
last menu (or menus) in your menu bar. Apple also reserves the right to add other 
system-handled menus to your application’s menu bar; for compatibility you should 
define your menu bar such that there is room for the Help, Keyboard, and Application 
menus and at least one additional system-handled menu. 


Your application does not need to take any action if the user chooses an item from the 
Keyboard or Application menu; the Menu Manager performs any appropriate actions for 
these two menus. If the user chooses an item that your application added to the Help 
menu, your application should perform the corresponding action. 


The following sections describe the Help, Keyboard, and Application menus in more 
detail, and they also describe other menus in a typical application, including the Apple, 
File, and Edit menus. 


The Apple Menu 


You should define the Apple menu as the first menu in your application. The title of the 
Apple menu is the Apple icon. The Apple menu of an application typically provides an 
About command as the first menu item, followed by a divider, which is followed by a 
list of all desktop objects contained in the Apple Menu Items folder. (The phrase desktop 
objects refers to applications, desk accessories, documents, folders, and any other item 
that can reside in the Apple Menu Items folder.) The items following the divider in the 
Apple menu are listed in alphabetical order. Each item below the divider lists a desktop 
object and the small icon for that object. 


Figure 3-9 shows the Apple menu for the SurfWriter application as it might appear on a 
particular user’s system. 


To create the items in your application’s Apple menu, define the Apple menu title, the 
characteristics of your application’s About command, and the divider following it ina 
"MENU ' resource. 


To insert the items contained in the Apple Menu Items folder into your application’s 
Apple menu, use the AppendResMenu or InsertResMenu procedure and specify 
"DRVR' as the resource type to add in the parameter theType. If you do this, these 
procedures automatically add all items in the Apple Menu Items folder in alphabetical 
order to the specified menu. 
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Figure 3-9 The Apple menu for the SurfWriter application 
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Note 

The Apple Menu Items folder is available in System 7 and later. In System 6, 
the AppendResMenu and InsertResMenu procedures add only the desk 
accessories in the System file to the specified menu when you specify 
'DRVR' as the resource type to add in the parameter theType. ¢@ 


The user can place any desktop object in the Apple Menu Items folder. When the user 
places an item in this folder, the system software automatically adds it to the list of items 
in the Apple menu of all open applications. 


When the user chooses an item other than your application’s About command from 

the Apple menu, your application should call the OpenDeskAcc function. The 
OpenDeskAcc function prepares to open the desktop object chosen by the user; for 
example, if the user chooses the Alarm Clock desk accessory, the OpenDeskAcc function 
prepares to open the Alarm Clock. The OpenDeskAcc function schedules the Alarm 
Clock desk accessory for execution and returns to your application. On your 
application’s next call to WaitNextEvent, it receives a suspend event, and then 

the Alarm Clock desk accessory becomes the foreground process. 


If the user chooses a desktop object other than a desk accessory or an application, the 
OpenDeskAcc function also takes the appropriate action. For example, as shown in 
Figure 3-9, if the user chooses a document called MyTideReport created by the 
SurfWriter application, the O(penDeskAcc function prepares to open the SurfWriter 
application (if it isn’t already open) and schedules the SurfWriter application for 
execution. The SurfWriter application is instructed to open the MyTideReport document 
when it becomes the foreground process. 


When the user chooses your application’s About command, your application can 
display a dialog box or an alert box that contains your application’s name, version 
number, copyright information, or other information as necessary. Your application 
should provide an OK button in the dialog box; the user clicks the OK button to close 
the dialog box. 
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Figure 3-10 shows the alert box that the SurfWriter application displays when the user 
chooses the About command from the application’s Apple menu. 


Figure 3-10 Choosing the About command of the SurfWriter application 
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If your application provides any application-specific Help commands, place these in the 
Help menu, not the Apple menu. 


The File Menu 


The standard File menu contains commands related to managing documents. For 
example, the user can open, close, save, or print documents from this menu. The user 
should also be able to quit your application by choosing Quit from the File menu. 


Your application should support the menu commands of the standard File menu. If you 
add other commands to your application’s File menu, they should pertain to managing 
a document. 


Figure 3-11 shows the standard File menu for applications. 


Figure 3-11 The standard File menu for an application 
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Table 3-4 describes the standard commands in the File menu and the actions your 
application should take when a user chooses them. 


Table 3-4 Actions for standard File menu commands 

Command Action 

New Open a new, untitled document. 

Open... Display the Open dialog box using the Standard File Package. 
Close Close the active window (which may be a document window, 


modeless dialog box, or other type of window). If the active window 
is a document and the document has been changed since the last 
save, display a dialog box asking the user if the document should be 
saved before closing. 


Save Save the active document to a disk, including any changes made to 
that document since the last time it was saved. If the user chooses 
Save for a new untitled document (one that the user hasn’t named 
yet), display the Save dialog box using the Standard File Package. 


Save As... Save a copy of the active document under a new name provided by 
the user. Display the Save dialog box using the Standard File 
Package. After your application saves the document, the document 
should remain open and active. 


Page Setup... Display the Page Setup dialog box to let the user specify printing 
parameters such as the paper size and printing orientation. Your 
application can provide other printing options as appropriate. Your 
application should save the user’s Page Setup printing preferences 
for the document when the user saves the document. 


Print... Display the Print job dialog box to let the user specify various 
parameters, such as print quality and number of copies. Print the 
document if the user clicks the Print button. The options specified in 
the Print dialog box apply to only the current printing operation, and 
your application should not save these settings with the document or 
restore the settings when the user chooses Print again. 


Quit Quit your application after performing any necessary cleanup 
operations. If any open documents have been changed since the user 
last saved them, display the Save dialog box once for each open 
document that requires saving. If any background or lengthy 
operation is still in progress, notify the user, giving the user the 
option to continue and not quit the application. 


See Macintosh Human Interface Guidelines for additional commands that you can provide 
in the File menu. See the chapter “Introduction to File Management” in Inside Macintosh: 
Files for information on how to perform the actions associated with the commands in the 
File menu. See the chapter “Standard File Package” in Inside Macintosh: Files for 
information on the standard file dialog boxes. See the chapter “Printing Manager” in 
Inside Macintosh: Imaging for information on displaying the Page Setup and Print job 
dialog boxes. 
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The New, Open, Close, Save, Print, and Quit commands have the keyboard equivalents 
shown in Figure 3-11 on page 3-22. These keyboard equivalents are reserved for these 
menu commands; do not assign these keyboard equivalents to any menu command 
other than the ones shown in Figure 3-11. 


The Edit Menu 


The standard Edit menu provides commands that let users change or edit the contents of 
their documents. It also provides commands that allow users to share data within and 
between documents created by different applications using editions or the Clipboard. All 
Macintosh applications should support the Undo, Cut, Copy, Paste, and Clear 
commands. Use these commands to provide standard text-editing abilities in your 
application. 


Figure 3-12 shows the standard Edit menu supported by Macintosh applications. 


Figure 3-12 The standard Edit menu for an application 
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The standard editing commands (Undo, Cut, Copy, Paste, and Clear) in your 
application’s Edit menu should appear in the order shown in Figure 3-12. Whenever 
possible, you should add an additional word or phrase to clarify what action your 
application will reverse when the user chooses the Undo command. For example, 
Figure 3-12 shows an application’s Edit menu that uses the phrase Undo Typing when 
typing was the last action performed by the user. If your application can’t undo the last 
operation, you should change the text of the Undo command to Can’t Undo and disable 
the menu item. See “Changing the Text of an Item” on page 3-59 for an example of how 
to change the text of a menu item. 


You can include other commands in your application’s Edit menu if they’re related to 
editing or changing the content of your application’s documents. If you add commands 
to the Edit menu, add them after the standard menu commands. For example, if 
appropriate, your application should support a Select All command. If your application 
supports both the Clear and Select All commands, they should appear in the order 
shown in Figure 3-12. 
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Table 3-5 describes the standard commands in the Edit menu and the actions your 
application should take when a user chooses them. 


Table 3-5 Actions for standard Edit menu commands 
Command Action 
Undo Reverse the effect of the previous operation. You should add the 


name of the last operation to the Undo command. For example, 
change the item to read Undo Typing if the user just finished 
entering some text in a document. If your application cannot 
undo the previous operation, disable this menu item and 
change the phrase to Can’t Undo. 


Cut Remove the data in the current selection, if any. Store the cut 
selection in the scrap (on the Clipboard). This replaces the 
previous contents of the scrap. 


Copy Copy the data in the current selection, if any. Copy the selection 
to the scrap (the Clipboard). This replaces the previous contents 
of the scrap. 

Paste Paste the data from the scrap at the insertion point; this replaces 
any current selection. 

Clear Remove the data in the highlighted selection; do not copy the 
data to the scrap (Clipboard). 

Select All Highlight all data in the document. 

Create Publisher... Display the Create Publisher dialog box (using the Edition 


Manager). Create an edition based on the selected data if the 
user clicks the Publish button. 


Subscribe To... Display the Subscribe To dialog box (using the Edition 
Manager). Allow the user to insert data from an edition if the 
user clicks the Subscribe button. 


Publisher Options... Display the Publisher Options dialog box (using the Edition 
Manager) and allow the user to set or change options associated 
with the publisher. Change this menu item to Subscriber 
Options if the current selection includes a subscriber. When the 
user chooses the Subscriber Options command, display the 
Subscriber Options dialog box. 





Show Clipboard Display the contents of the Clipboard in a window. Change 
this item to Hide Clipboard when the Clipboard window is 
showing. When the user chooses Hide Clipboard, hide the 
window displaying the Clipboard contents and change the 
menu item to Show Clipboard. 


The Undo, Cut, Copy, Paste, and Select All commands have the keyboard equivalents 
shown in Figure 3-12 on page 3-24. These keyboard equivalents are reserved for these 
menu commands; do not assign these keyboard equivalents to any menu command 
other than the ones shown in Figure 3-12. See the chapter “Scrap Manager” in Inside 
Macintosh: More Macintosh Toolbox for information on copying data to and from the scrap. 
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See the chapter “Edition Manager” in Inside Macintosh: Interapplication Communication for 
information on supporting the Create Publisher, Subscribe To, and Publisher Options 
commands in your application. 


The Font Menu 


You can provide a Font menu to allow the user to choose text fonts. A font is a complete 
set of characters created in one typeface and font style. The characters in a font can 
appear in many different point sizes, but all have the same design elements. 


You should list the names of all currently available fonts in your application’s Font 
menu. The currently available fonts are those fonts residing in the Fonts folder of the 
user’s System Folder (or in earlier versions of system software, in the user’s System file). 


You add fonts to the Font menu using the AppendResMenu or InsertResMenu 
procedure. These two procedures add items to the specified menu in alphabetical order. 


The user can install a large number of fonts and thereby create a very large Font menu. 
Therefore, you should never include other items in the Font menu. Use separate menus 
to accommodate lists of attributes such as style and size choices. You can also provide a 
Size menu to allow the user to choose a specific point size of a font; the next section 
describes the Size menu. 


Figure 3-13 shows a typical Font menu. Your application should indicate which typeface 
is in use by adding a checkmark to the left of the name of the current font. In Figure 3-13, 
the application has placed a checkmark next to Palatino to indicate that Palatino® is the 
current font. When the user starts entering text at the insertion point, your application 
should display text in the current font. 


Figure 3-13 A typical Font menu 
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In the Font menu, you can use dashes to indicate that the selection contains more than 
one font. (Place a checkmark next to an item if the entire selection contains only one 
font.) If the current selection contains more than one font, place a dash next to the name 
of each font that the selection contains. See “Changing the Mark of Menu Items” on 
page 3-61 for information on adding dashes and checkmarks to a menu item. 
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Figure 3-14 shows the use of dashes to indicate that a selection contains more than one 
font. In this figure, part of the selection contains a Helvetica® font and part of the 
selection contains a Palatino font. 


Figure 3-14 A Font menu showing a selection containing more than one font 
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The AppendResMenu and InsertResMenu procedures can recognize when an added 
font resource is associated with a script other than the current system script (non-Roman 
fonts have font numbers greater than $4000). The Menu Manager displays a font name in 
its corresponding script if the script system for that font is installed. 


You can choose to provide a Size menu and a Style menu in addition to a Font menu. 
If you do so, these three menus typically appear in the order Font, Size, Style in 
most applications. 


The Size Menu 


Your application can provide a Size menu to allow the user to choose sizes for fonts. Font 
sizes are measured in points. A point is a typographical unit of measure equivalent (on 
Macintosh computers) to 1/72 of an inch. 


Your application should indicate the current point size by adding a checkmark to the 
menu item of the current size. You can use dashes if the selection contains more than one 
point size. 


System 7 supports both bitmapped and TrueType fonts. TrueType fonts can be displayed 
in a wider range of point sizes, for example, 12 points, 51 points, 156 points, 578 points, 
or greater. Your application should not provide an upper limit for font sizes. 


In the Size menu, your application should outline font sizes to indicate which sizes are 
directly provided by the current font. If the user chooses a TrueType font, outline all sizes 
of that font in the Size menu. If the user chooses a bitmapped font, outline only those 
sizes that appear in the Fonts folder. Use plain type for all other font sizes. See the 
chapter “Font Manager” in Inside Macintosh: Text for additional information on 
supporting fonts in your application. 
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Figure 3-15 shows a typical Size menu of an application. 


Figure 3-15 A typical Size menu 
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Your application should also provide a method that allows users to choose any point 
size. You can add an Other command to the end of the Size menu for this purpose. When 
the user chooses this command, display a dialog box that allows the user to choose any 
available font size. You can include an editable text item in which the user can type the 
desired font size. Figure 3-16 shows a dialog box an application might display when the 
user chooses the Other command from the Size menu. 


Figure 3-16 A dialog box to select a new point size for a font 
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Figure 3-17 shows the Other dialog box after the user has entered a new font size 
of 31. 
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Figure 3-17 Entering a new point size for a font 
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If the user enters a font size not currently in the menu, your application should add a 
checkmark to the Other menu command and include the font size as part of the text of 
the Other command. You should show the font size in parentheses after the text Other, 
as shown in Figure 3-18. 


Figure 3-18 The Other command with a font size added to it 
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If a selection contains more than one nonstandard size, you should include the text 
Mixed in parentheses following the word Other. In this case leave the editable text field 
of the Other dialog box blank when the user chooses the Other (Mixed) command. 


See “Handling a Size Menu” on page 3-82 for more information on how to respond to 
the user’s choice of a command from the Size menu. See the chapter “Dialog Manager” 
for information on creating a dialog box. 


The Help Menu 


The Help menu is specific to each application, just as the Apple, File, and Edit menus 
are. The Help menu items defined by the Help Manager are common to all applications 
and give the user access to Balloon Help. 


You can add menu items to your application’s Help menu to give your users access 
to any online help that your application supplies in addition to help balloons. If you 
currently provide your users with help information when they choose the About 
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command from the Apple menu, you should instead append a command for your own 
help to the Help menu. This gives users one consistent place to obtain help information. 


When adding your own items to the Help menu, include the name of your application in 
the command so that users can easily determine which application the help relates to. 


Figure 3-19 shows the Help menu for the SurfWriter application. This application 
appends one item to the end of the standard Help menu: SurfWriter Help. When the 
user chooses this item, the application provides access to any application-specific 
help information. 


Figure 3-19 The Help menu of the SurfWriter application 
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You add items to the Help menu by using the HMGet Hel pMenuHand1le function and the 
AppendMenu procedure. Apple reserves the right to change the number of standard 
items in the Help menu. You should always append any additional items to the end. See 
“Adding Items to the Help Menu” on page 3-67 for specific examples. 


The user turns Balloon Help on or off by choosing Show Balloons or Hide Balloons from 
the Help menu. The Help Manager automatically enables or disables Balloon Help when 
the user chooses Show Balloons or Hide Balloons from the Help menu. The setting of 
help is global and affects all applications. 


When the user turns on Balloon Help, the Help Manager displays small help balloons as 
the user moves the cursor over areas such as scroll bars, buttons, menus, or rectangular 
areas in windows or dialog boxes that have help information associated with them. 
Help balloons are rounded-rectangle windows that contain explanatory information for 
the user. 


The Help Manager provides help balloons for the menu titles of the Apple, Help, 
Application, and Keyboard menus. The Help Manager also provides help balloons for 
menu items in the Application and Keyboard menus, for any item from the Apple Menu 
Items folder in the Apple menu, and for the standard items in the Help menu. The Help 
Manager provides these help balloons only if your application uses the standard menu 
definition procedure. 


Your application should provide the content of help balloons for all other menu items 
and menus in your application. 


Figure 3-20 shows the default help balloons for the Apple menu title and Application 
menu title. 
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Figure 3-20 Default help balloons for the Apple menu and Application menu 
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Figure 3-21 shows help balloons for an application’s Cut command when it is enabled 
and when it is disabled. 


Figure 3-21 Help balloons for different states of the Cut command 
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Your application can provide the content for help balloons for your menus and menu 
items. You define the help balloons for your application using 'hmmu' resources. 


For information on how to define the help balloons for your application’s menus 
in 'hmmu' resources, see the chapter “Help Manager” in Inside Macintosh: More 
Macintosh Toolbox. 
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The Keyboard Menu 


The Keyboard menu displays a list of all the keyboard layouts and input methods that 
are available for each enabled script system. Each script system has at least one keyboard 
layout or input method associated with it. If only the Roman script system and the U.S. 
keyboard layout are available, the Menu Manager does not add the Keyboard menu 
(unless the smfShowIcon bit is set in the flags byte of the 'it1lc' resource). If the 
user’s system includes an additional script system or includes additional keyboard 
layouts for the Roman script system and the smfShowIcon bit is set in the 'itlc' 
resource, the Menu Manager adds the Keyboard menu to your application’s menu 

bar as long as your application’s menu bar includes an Apple menu. The Menu 
Manager adds the Keyboard menu to the right of the Help menu and to the left of the 
Application menu. 


Figure 3-22 shows a Keyboard menu as it might appear on a particular user’s system. 
System software groups the items in the Keyboard menu by their script systems. For 
example, in Figure 3-22 seven script systems are shown: Arabic, Roman, Cyrillic, 
Hebrew, Thai, Japanese, and Korean. Two keyboard layouts are available in the user’s 
system for the Arabic script system, two keyboard layouts for the Roman script system, 
one keyboard layout for the Cyrillic script system, two keyboard layouts for the Hebrew 
script system, three keyboard layouts for the Thai script system, two input methods for 
the Japanese script system, and one input method for the Korean script system. 


Figure 3-22 Accessing the Keyboard menu from an application 
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When the user chooses an item from the Keyboard menu, the Menu Manager handles it 
appropriately. For example, if the user chooses a different keyboard layout in a different 
script, the Menu Manager changes the current keyboard layout and script system to the 
item chosen by the user. See Inside Macintosh: Text for further information on supporting 
text and handling text in multiple scripts in your application. 


The Application Menu 


The Application menu is the menu farthest to the right in the menu bar; the Application 
menu contains the icon of the active application or desk accessory for its menu title. 


The Menu Manager automatically appends the Application menu to your application’s 
menu bar if your menu bar includes an Apple menu. 


When the user chooses an item from the Application menu, the Menu Manager handles 
the event as appropriate. For example, if the user chooses the Hide Others command, the 
Menu Manager hides the windows of all other open applications. If the user chooses 
another application from the Application menu, the Menu Manager sends your 
application a suspend event. Your application receives the suspend event the next time it 
calls WaitNextEvent, and your application is switched out after handling the suspend 
event. (See the chapter “Event Manager” in this book for information about responding 
to suspend and resume events.) 





Figure 3-23 shows the Application menu for the SurfWriter application as it appears 
when both SurfWriter and TeachText are open and the user is currently interacting with 
SurfWriter. The checkmark next to the menu item showing SurfWriter’s icon indicates 
that SurfWriter is the active application. 


Figure 3-23 SurfWriter’s Application menu 
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Pop-Up Menus 


You can use pop-up menus to present the user with a list of choices in a dialog box or 
window. Pop-up menus are especially useful in dialog boxes that require the user to 
select one choice from a list of many or to set a specific value. 


In System 7, the standard pop-up menu is implemented by a control definition function. 
This section explains how the standard pop-up control definition function provides 
support for pop-up menus. The chapter “Control Manager” in this book explains 
controls in detail. 
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A pop-up menu appears as a rectangle with a one-pixel border and a one-pixel drop 
shadow. Pop-up menus are identified by a downward-pointing triangle that appears 
in the pop-up box. The title of the pop-up menu appears next to the pop-up box. 
Figure 3-24 shows a pop-up menu. 


Figure 3-24 A pop-up menu 
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To display a pop-up menu, the user presses the mouse button while the cursor is over 
the pop-up title or pop-up box. If the pop-up menu is in a dialog box and your 
application uses the Dialog Manager, the Dialog Manager uses the pop-up control 
definition function to display the pop-up menu and to handle all user interaction in the 
pop-up menu. If the pop-up menu is in one of your application’s windows, your 
application needs to determine which control the cursor was in when the user pressed 
the mouse button. Your application can then use the Control Manager routines to display 
the pop-up menu and to handle user interaction in the control. 


Just like MenuSelect, the pop-up control definition function highlights the pop-up 
menu title and highlights menu items appropriately as the user drags the cursor through 
the menu items. The pop-up control definition function also highlights the default 
(current) menu item when the pop-up menu is first displayed and adds the checkmark to 
the menu item. Once the user releases the mouse button, the pop-up control definition 
function causes the chosen item (if any) to blink, unhighlights the menu title, changes the 
text in the pop-up box, and stores the item number of the chosen item as the value of the 
control. Your application can use the Control Manager function Get Cont rolValue to 
get the menu item chosen by the user. 


Figure 3-25 shows a pop-up menu in its closed state (as it appears initially to the user) 
and its open state (as it appears when the user presses the mouse button while the cursor 
is in the pop-up menu). 


Figure 3-25 A pop-up menu in its closed and open states 
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If you don’t provide a title for a pop-up menu, the current menu item serves as the title. 
In most cases you should create pop-up menus that have titles. Choose a title that reflects 
the contents of the menu or indicates the purpose of the menu. 
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Figure 3-26 shows the process of a user making a selection from a pop-up menu. 


Figure 3-26 Making a selection from a pop-up menu 
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In step 1 in Figure 3-26, the user presses the mouse button while the cursor is over the 
pop-up box. When this occurs, your application can use the Dialog Manager or Control 
Manager to call the pop-up control definition function. In step 2, the pop-up control 
definition function highlights the title of the pop-up menu, removes the downward- 
pointing triangle from the pop-up box, adds a checkmark to the current item, highlights 
the current item, and displays the contents of the pop-up menu. In step 3, the pop-up 
control definition function handles all user interaction, highlighting and unhighlighting 
menu items, until the user releases the mouse button. When the user releases the mouse 
button, the pop-up control definition function closes the pop-up menu, unhighlights the 
pop-up menu title, sets the text of the pop-up box to the item chosen by the user, and 
stores the item number of the chosen item as the value of the control. Step 4 shows the 
appearance of the closed pop-up menu after the pop-up control definition function 
performs these actions. 


If your application does not use the standard pop-up control definition function, you 
can create your own control definition function and you can choose to use the 
PopUpMenuSelect function to help your application handle pop-up menus. In this 
case, when the user presses the mouse button when the cursor is in a pop-up menu, 
your application should call the PopUpMenuSelect function. Your application must 
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highlight the pop-up title before calling PopUpMenuSelect and unhighlight it 
afterward. The PopUpMenuSelect function displays the pop-up menu and highlights 
menu items appropriately as the user drags the cursor through the menu items. Once the 
user releases the mouse button, PopUpMenuSelect flashes the chosen item, if any, and 
returns information indicating which menu item was chosen to your application. Your 
application is responsible for highlighting and unhighlighting the menu title, updating 
the text in the pop-up box, and storing any changes to the settings of the menu items if 
you use the PopUpMenuSelect function. 


Pop-up menus work well when your application needs to present several choices to the 
user. Note that pop-up menus hide these choices from the user until the user chooses to 
display the pop-up menu. Use pop-up menus when the user doesn’t need to see all the 
choices all the time. For example, Figure 3-27 shows a dialog box that uses a pop-up 
menu to allow the user to choose one color from a list of many. 


Figure 3-27 Choosing one attribute from a list of many 





Column Style 


Colors: @® To scale 
Not to scale 
~~ Columns ---- 


: fj Doric 


© lonic 
: © Corinthian 





If you need to show only a few choices, you may find that using checkboxes or radio 
buttons is more appropriate for your application. For example, in Figure 3-27 the 
selection of columns is implemented with radio buttons rather than a pop-up menu. 
Whenever possible, you should show all available choices to the user. Note that in this 
example the amount of space occupied by the radio buttons is about the same as the 
amount of space required for a corresponding pop-up menu. 


Use pop-up menus to allow the user to choose one option from a set of many choices. 
Don’t use a pop-up menu for multiple-choice lists where the user can make more than 
one selection. If you do, the text in the menu box will not fully describe the selections in 
effect. For example, don’t use a pop-up menu for font style selections. In a dialog box, 
font style selections are more appropriately implemented as checkboxes. Figure 3-28 
shows a dialog box that uses checkboxes instead of a pop-up menu to allow the user to 
select more than one font style. The Size and Font choices are implemented as pop-up 
menus in this example, since the user can choose only one size and one font from a list 
of many. 
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Figure 3-28 A dialog box with checkboxes and pop-up menus 
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Never use a pop-up menu as a way to provide more commands. Pop-up menus should 
not contain actions (verbs) but can contain attributes (adjectives) or settings that allow 
the user to choose one from many. For these reasons, you should not use Command-key 
equivalents for pop-up menu items. 


Your application can also use type-in pop-up menus when appropriate. Use a type-in 
pop-up menu to give the user a list of choices and to allow the user to type in an 
additional choice. The standard pop-up control definition function that implements 
pop-up menus does not provide specific support for type-in menus. You can create your 
own control definition function to handle type-in pop-up menus. If you do so, your 
type-in pop-up menu should adhere to the guidelines described here. Figure 3-29 shows 
a typical type-in pop-up menu in its closed and open states. 


Figure 3-29 A type-in pop-up menu in its closed and open states 





Your application is responsible for drawing and highlighting the type-in field of the 
pop-up menu. Your application does not need to highlight the title of a type-in pop-up 
menu; your application should highlight the type-in field instead. 


If the user types in a value that is already in the menu, make that item the current item. If 
the user types a value that does not match any of the items in the pop-up menu, add the 
item to the top of the menu and add a divider below the item to separate it from the rest 
of the standard items. Figure 3-30 on the next page shows a type-in pop-up menu witha 
user’s choice added to it. 
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Figure 3-30 A type-in pop-up menu with a user's choice added 
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A type-in pop-up menu should allow the user to type in a single additional choice. That 
is, a standard type-in pop-up menu does not accumulate the user’s choices in the menu. 
For example, if the user types in a value of 13, then types in a new choice, such as 43, the 
menu should appear as shown in Figure 3-30, except that the type-in field and menu 
item that previously contained 13 is replaced by 43. 


A type-in pop-up menu should also allow the user to type in any of the standard values 
in the menu or choose any of the standard items in the pop-up menu. If the user types in 
or chooses any of the standard items, you should remove any user-specified item 
previously added to the menu. For example, as shown in Figure 3-30, the user specified a 
nonstandard size of 13. If the user then types in or selects 9, your application should 
return the pop-up menu to its standard state, as shown in Figure 3-29 on page 3-37. 


Hierarchical Menus 


A hierarchical menu is a menu that has a submenu attached to it. Hierarchical menus can 
be useful when your application needs to offer additional choices to the user without 
taking up extra space in the menu bar. If you use a hierarchical menu in your 
application, use it to give the user additional choices or to choose attributes, not to 
choose additional commands. 


In a hierarchical menu, a menu item serves as the title of a submenu; this menu item 
contains a triangle to identify that the item has a submenu. The triangle appears in the 
location of the keyboard equivalent. The title of a submenu should represent the choices 
it contains. Figure 3-31 shows a menu with a submenu whose menu title is Label Style. 


When a user drags the cursor through a hierarchical menu and rests the cursor on a 
menu item that has a submenu, the Menu Manager displays the submenu after a brief 
delay. The title of the submenu remains highlighted while the user browses through the 
submenu; the Menu Manager unhighlights the menu title of the submenu when the user 
releases the mouse button. 


Hierarchical menus are useful for providing lists of related items, such as font sizes and 
font styles. Never use more than one level of hierarchical menus (in other words, don’t 
attach a submenu to another submenu). You can assign keyboard equivalents to the 
menu items of a submenu; however, if you do so, you make it harder for the user to 
quickly scan all menus for their keyboard equivalents. 
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Figure 3-31 A hierarchical menu item and its submenu 
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About the Menu Manager 


The Menu Manager, together with the menu definition procedure and menu bar 
definition function, provides your application with a convenient way to manage the 


menus in your application. The Menu Manager uses two data structures, menu records 


and menu lists, to manage menus. The next two sections describe how the Menu 


Manager uses these two data structures. “Using the Menu Manager,” which begins on 


page 3-41, shows how you can use the Menu Manager to 


m define a menu using a 'MENU' resource 

m define a menu bar using an 'MBAR' resource 
m install your application’s menu bar 

m change the appearance of menu items 


m add menu items to a menu 


m respond to the user when the user chooses a menu item 


m handle the Apple and Help menus 
m create a pop-up menu 


m create a hierarchical menu 


m handle access to menus when your application displays a dialog box 


m write your own menu definition procedure 
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How the Menu Manager Maintains Information About Menus 


The Menu Manager maintains information about menus in menu records. Each menu 
record includes certain information about a specific menu, including 


m the menu ID of the menu 
m the horizontal and vertical dimensions of the menu (in pixels) 
m a handle to the menu definition procedure of the menu 


m flags indicating whether each item (for the first 31 items) is enabled or disabled and 
whether the menu title is enabled or disabled 


m the contents of the menu, including the menu title and other data that defines the 
menu items 


You typically specify most of this information in a menu resource, that is, a resource of 
type 'MENU'. When you create a menu, the Menu Manager stores this information in a 
menu record. A menu record is a data structure of type MenuInfo. You usually never 
need to access the information in the menu record directly; the Menu Manager 
automatically updates the menu record when you make any changes to the menu, such 
as adding a menu item. See “The Menu Record” beginning on page 3-95 if you need to 
access the fields of the menu record directly. 





The Menu Manager identifies every menu by a number referred to as a menu ID. You 
must assign a menu ID to each menu in your application. Each menu in your application 
must have a menu ID that is unique from that of any other menu in your application. 
You can use any number greater than 0 for a menu ID of a pull-down or pop-up menu; 
submenus of an application can use only menu IDs from 1 through 235; submenus of a 
desk accessory must use menu IDs from 236 through 255. 


When you create a menu, the Menu Manager creates a menu record for the menu and 
returns a handle to that menu record. To refer to a menu, you usually use either the 
menu’s menu ID or a handle to the menu’s menu record. 


To refer to a menu item, use the menu item’s item number. Item numbers identify items 
in menus; items are assigned item numbers starting with 1 for the first menu item in the 
menu, 2 for the second menu item in the menu, and so on, up to the number of the last 
menu item in the menu. 


How the Menu Manager Maintains Information About an 
Application’s Menu Bar 


A menu list contains handles to the menu records of one or more menus (although a 
menu list can be empty). The end of a menu list can contain handles to the menu 
records of submenus and pop-up menus; the phrase submenu portion of the menu list 
refers to this portion of the menu list, which contains information about submenus 
and pop-up menus. 


When your application initializes the Menu Manager, the Menu Manager allocates the 
current menu list, which is initially empty. The contents of the current menu list change 
as your application adds menus to or removes menus from it. 


About the Menu Manager 


CHAPTER 3 


Menu Manager 


The current menu list contains handles to the menu records of all menus in the current 
menu bar and the menu records of any submenus or pop-up menus that you have 
inserted into the current menu list. Your application typically creates a menu list using 
GetNewMBar, and it then sets the current menu list to its newly created menu list using 
SetMenuBar. You can insert other menus in the current menu list using the GetMenu 
function and InsertMenu procedure. 





The Menu Manager displays the menu bar and the titles of all pull-down menus that 
are defined in the current menu list when your application calls the DrawMenuBar 
procedure. The Menu Manager displays the menus in the menu bar in the same order 
that they appear in the current menu list. 





The Menu Manager provides routines for adding menus to and removing menus from 
the current menu list; your application should never access a menu list directly. To refer 
to a menu list, use the handle returned by Get NewMBar or GetMenuBar. 


The Menu Manager inserts the Help menu, the Keyboard menu if necessary, and the 
Application menu into your application’s menu list if your application calls the 
GetNewMBar function and your menu bar includes an Apple menu; your application 
then uses SetMenuBar to set the current menu list to the newly created menu list. The 
Menu Manager also inserts these menus into your application’s current menu list if your 
application inserts the Apple menu into the current menu list using the InsertMenu 
procedure. Therefore, you should not make any assumptions about the last menu (or 
menus) in your application’s current menu list. 


When your application inserts a submenu into the current menu list, the Menu Manager 
stores a handle to the menu record of the submenu in the submenu portion of the current 
menu list. Similarly, when your application inserts a pop-up menu into the current menu 
list, the Menu Manager stores a handle to the menu record of the pop-up menu in the 
submenu portion of the current menu list. 


Using the Menu Manager 


You can define your application’s menus and menu bar as resources and use Menu 
Manager routines to create and manage them. For example, whenever the user presses 
the mouse button while the cursor is in the menu bar, your application should call the 
MenuSelect function, allowing the user to choose a command from any menu. The 
MenuSelect function handles all user activity until the user releases the mouse button. 
The MenuSelect function displays and removes menus as the user drags the cursor 
through the menu bar, and it highlights enabled menu items as the user drags through 

a menu. 


You should provide help balloons for each menu title and menu item of your applica- 
tion. You store information and text for help balloons in resources. See the chapter 
“Help Manager” in Inside Macintosh: More Macintosh Toolbox for complete and specific 
information on how to provide help balloons for the menus of your application. The 
BalloonWriter application, available from APDA, can also help you create help balloons 
for the menus of your application. 
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Your application needs to initialize QuickDraw, the Font Manager, and the Window 
Manager before using the Menu Manager. Your application can accomplish this using 
the InitGraf, InitFonts, and InitWindows procedures. To initialize the Menu 
Manager, use the InitMenus procedure. 


If your application uses pop-up menus, use the Gestalt function with the 
gestaltPopUpAttr selector to determine if the control definition function for 
pop-up menus is available. See Inside Macintosh: Operating System Utilities for 
information about the Gestalt function. 


To create the pull-down menus in your application’s menu bar, you need to 
m create descriptions of each pull-down menu in 'MENU' resources 
m create an 'MBAR' resource that lists the order and resource ID of each menu 


m use the GetNewMBar function and SetMenuBar procedure to set up your menu bar 
and use the DrawMenuBar procedure to draw your menu bar 


The next section, “Creating a Menu,” explains these steps in detail. 


After creating your application’s menu bar, you can enable or disable your menu items, 
add marks such as checkmarks or dashes to menu items, or add items to any of your 
menus as needed. See “Enabling and Disabling Menu Items” on page 3-58, “Changing 
the Mark of Menu Items” on page 3-61, and “Adding Items to a Menu” beginning on 
page 3-64 for information on these topics. 


“Handling User Choice of aMenu Command,” beginning on page 3-70, shows how to 
handle mouse-down events in the menu bar, adjust the menus of your application, and 
determine if the user chose a keyboard equivalent of a command. 


“Responding When the User Chooses a Menu Item,” beginning on page 3-78, describes 
how your application should respond once the user chooses an item and also shows how 
to handle the user’s choice of a command from the Apple and Help menus. 


If your application displays dialog boxes, see “Accessing Menus From a Dialog Box” 
beginning on page 3-84. 


Finally, if your application needs to create submenus or pop-up menus, see “Creating a 
Hierarchical Menu” on page 3-53 and “Creating a Pop-Up Menu” on page 3-56. 


Creating a Menu 


You use various Menu Manager routines to set up the menus and the menu bar 
for your application. You can use any of these methods to create pull-down menus for 
your application: 


m You can create descriptions of your application’s menus in 'MENU' resources and 
describe your application’s menu bar in an 'MBAR' resource. You use the 
GetNewMBar function to read in descriptions of your menu bar and menus and create 
anew menu list, use the SetMenuBar procedure to set the current menu list to your 
application’s menu list, and use the DrawMenuBar procedure to update the menu bar. 


m You can create descriptions of your application’s menus in 'MENU' resources, read 
them in using GetMenu, add them to the current menu list using InsertMenu, and 
update the menu bar using DrawMenuBar. 
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m You can use NewMenu to create new empty menus; use AppendMenu, 
InsertMenulItem, InsertResMenu, or AppendResMenu to fill the menus with 
menu items; add the menus to the current menu list using InsertMenu; and update 
the menu bar using DrawMenuBar. 








Whenever possible you should define your menus in menu ('MENU') resources and 
your menu bar in a menu bar ('MBAR') resource to make your application easier 
to localize. 


To create a hierarchical menu, you need to create descriptions of the submenu and the 
menu to which the submenu is attached. Usually you create the description of both 
menus in 'MENU' resources. You typically read in the description of the hierarchical 
menu using Get NewMBar (if you also provide an 'MBAR" resource). To read in the 
description of the submenu and insert it in the current menu list, use the GetMenu 
function and InsertMenu procedure. 





To create a pop-up menu, create descriptions of the pop-up menu and its menu items, 
create a control that uses the pop-up control definition function, and associate the control 
with a window or dialog box. You can display and manage the pop-up menu using the 
Dialog Manager or Control Manager routines. 


Once the Menu Manager creates a menu for your application, if necessary you can add 
additional menu items to the menu using AppendMenu, InsertMenulItem, 
InsertResMenu, or AppendResMenu. You can use various Menu Manager routines to 
change the appearance of menu items. 





The next sections describe how to create 'MENU' and 'MBAR' resources. “Creating a 
Hierarchical Menu” on page 3-53 describes how to create a menu that has a submenu, 
and “Creating a Pop-Up Menu” on page 3-56 describes how to create pop-up menus. 


Creating a Menu Resource 





Usually you should define your menus in menu ("MENU") resources so that you can 
easily localize the menu titles and menu items for other languages, cultures, or regions. 
A 'MENU' resource defines the menu title of a menu and the characteristics of menu 
items in a menu. Listing 3-1 shows a sample 'MENU' resource in Rez format for an 
application’s Apple menu. (Rez is a resource compiler available with MPW. You can also 
define menus using a resource utility, such as ResEdit, available from APDA.) 


Listing 3-1 Rez input fora 'MENU' resource for the Apple menu 


#define mApple 128 





resource 'MENU' (mApple, preload) { /*resource ID, preload resource*/ 
mApple, /*menu ID*/ 
textMenuProc, /*uses standard menu definition */ 


/* procedure*/ 


0b1111111111111111111111111111101, /*enable About item, */ 


/* disable divider, */ 


/* enable all other items*/ 
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enabled, /*enable menu title*/ 
apple, /*menu title*/ 
{ 
/*first menu item*/ 
"About SurfWriter...", /*text of menu item */ 
/* (includes ellipsis) */ 
/*item characteristics follow*/ 
noicon, /*icon number (if any) or */ 
/* script code (if any) */ 
nokey, /*keyboard equivalent (if any) */ 
/* or submenu (if any) or */ 
/* small or reduced icon (if any) */ 
nomark, /*marking character (if any) or */ 


/* menu ID of submenu (if any) */ 





plain; /*style of menu item text*/ 
/*second menu item*/ 
Bay /*item text (divider) */ 


noicon, nokey, nomark, plain /*item characteristics*/ 


You should also define help balloons for each of your application’s menu items and each 
menu title when you create your menus. (Figure 3-21 on page 3-31 shows help balloons 
for an application’s Cut command.) You define the help balloons for your application’s 
menus in 'hmmu' resources. See the chapter “Help Manager” in Inside Macintosh: More 
Macintosh Toolbox for examples of how to create 'hmmu' resources. 


Listing 3-1 defines the resource ID of the Apple menu as 128. You can use any number 
equal to or greater than 128 as a resource ID for a menu. By convention, many 
applications use 128 as the resource ID of the first menu in the application’s menu bar 
(the Apple menu) and use sequential numbers for the resource IDs of following menus. 


Listing 3-1 also defines the menu ID of the Apple menu as 128. Once your application 
creates the menu, the Menu Manager uses the defined menu ID to refer to this menu. 
The number you define for the menu ID of a menu does not have to match the resource 
ID of the menu, but it is usually more convenient to use the same number. You can use 
any number greater than 0 for the menu ID of a pull-down or pop-up menu; submenus 
of an application can only use menu IDs from 1 through 235; submenus of a desk 
accessory must use menu IDs from 236 through 255. 


The listing specifies that this menu uses the standard menu definition procedure. If you 
choose to create your own menu definition procedure, list its resource ID instead of the 
textMenuProc constant. 
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After the resource ID of the menu definition procedure is a 32-bit number (expressed as 
a 31-bit field followed by a Boolean field), where bits 1-31 indicate if the correspond- 
ing menu item is disabled or enabled, and bit 0 indicates whether the menu is enabled 
or disabled. 


The listing specifies in the 31-bit field that the first menu item should be enabled, that the 
second menu item should be disabled, and that the following menu items (item numbers 
3 through 31) should be enabled when the menu is first created. After creating a menu, 
your application can enable or disable menu items using the EnableItemor 
DisableItem procedure. If a menu contains more than 31 items, the Menu Manager 
automatically enables all items following the 31st item when the menu is enabled. Your 
application cannot disable any individual items following the 31st item. However, you 
can disable all items, including items after the 31st item, by disabling the entire menu. 








Listing 3-1 specifies that the menu title should be enabled when it is first created. 

Your application can also disable or enable the menu title using the DisableItemor 
EnableItem procedure. When you disable a menu using the DisableItem procedure, 
the Menu Manager disables all menu items in the menu (including any items following 
the 31st item) and dims the title of the menu. 





The resource listing identifies the title of the menu using the constant app1e. If you 
specify the apple constant as the title, the Menu Manager uses a small Apple icon as the 
title of the menu. The Menu Manager uses a color Apple icon if the monitor is set to 
display colors. The listing then defines the characteristics of each menu item in the 
menu. For each menu item, you need to define the text and any other characteristics of 
the menu item. For example, Listing 3-1 defines the first item in the Apple menu as the 
About command; note that the text of this menu item specifies three ellipsis points (...). 
Specify three ellipsis points following the text of a menu command if your application 
displays a dialog box requesting information from the user before performing the 
command. In general, you should not use ellipses if your application displays a 
confirmation alert after the user chooses a menu command; the About command is an 
exception to this guideline. 


Listing 3-1 defines other characteristics of the About command—it doesn’t have an 
icon to the left of the menu item text, it doesn’t have a keyboard equivalent, it doesn’t 
have any mark to the left of the menu item text, and the font style of the menu item 
text is plain. 


By specifying various combinations of values in the icon field and keyboard equivalent 
field, you can define an icon (normal, small, reduced, or color), a keyboard equivalent, a 
submenu, or the script code of a menu item. Note that some characteristics are mutually 
exclusive (for example, an item can have a keyboard equivalent or submenu, but not 
both), as described in the following paragraphs. Table 3-6 on page 3-46 summarizes how 
the Menu Manager interprets these item characteristics. 
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Table 3-6 Specifying submenus, script codes, reduced icons, small icons, and color icons of 
a menu item in a menu resource 


Marking 
Icon field character field Description 
Menu ID of Indicates the item has a submenu. The 
submenu marking character field specifies the 
menu ID of the submenu. 
Script code of Indicates the item text uses the script 
item text defined by the script code specified in the 
icon field. 
Icon number of Indicates the item has an icon defined by an 
"ICON ' resource "ICON" resource and that it should be 
reduced to fit in a 16-by-16 bit rectangle. 
Icon number Indicates the item has an icon defined by an 
of 'SICN' "SICN' resource. 
resource 
Icon number of Indicates the item has an icon defined 
"ICON" or by an 'ICON' ora 'cicn' resource. 
"cicn' resource (A value greater than $20 in the 


keyboard equivalent field specifies the 
item’s keyboard equivalent.) 


To assign an icon to a menu item, specify an icon number in place of the noicon 

constant. The icon number you specify should be a number from 1 through 255 (or from 
1 through 254 for small icons and reduced icons); add 256 to your icon number and use 
the result for the resource ID of the color icon ('cicn") resource, icon ("ICON") 
resource, or small icon ('SICN') resource that describes the icons for the menu item. You 
must define the icon for a menu item ina 'cicn',an 'ICON',oran 'SICN' resource; 

the Menu Manager uses only these types of resources for icons you define for your menu 
items. The Menu Manager first looks fora 'cicn' resource with the calculated resource 
ID and uses that icon if it finds it. If it doesn’t find a 'cicn' resource (or if the computer 
doesn’t have Color QuickDraw) and the keyboard equivalent field specifies $1E, the 
Menu Manager looks for an 'SICN' resource with the calculated resource ID. 
Otherwise, the Menu Manager looks for an 'ICON' resource and plots it in a 32-by-32 
bit rectangle, unless the keyboard equivalent field contains $1D. If the keyboard 
equivalent field contains $1D, the Menu Manager reduces the icon to fit in a 16-by-16 

bit rectangle. 


If you provide an 'ICON' resource and specify the nokey constant or a value greater 
than $20 as the keyboard equivalent, the Menu Manager enlarges the rectangle of the 
entire menu item to fit the 32-by-32 bit ' ICON" resource. If you specify a value of $1D as 
the keyboard equivalent of the menu item, the Menu Manager reduces the 'ICON' 
resource to fit in a 16-by-16 bit rectangle. If you provide an 'SICN' resource and specify 
a value of $1E as the keyboard equivalent of a menu item, the Menu Manager plots the 
small icon in a 16-by-16 bit rectangle. If you provide a 'cicn' resource, the Menu 
Manager automatically enlarges the enclosing rectangle of the menu item according to 
the rectangle specified in the 'cicn' resource. (For the Apple and Application menus, 
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the Menu Manager automatically reduces the icon to fit within the enclosing rectangle of 
a menu item or uses the appropriate icon from the application’s icon family, such as an 
"ics8"' resource, if one is available.) See the chapter “Finder Interface” in this book for 
details on how to create icons for your application. 


To assign a keyboard equivalent to a menu item, specify the 1-byte character that the 
user types in addition to the Command key in place of the nokey constant in your 
resource definition for the menu item. If your application attaches a submenu to a menu 
item, then specify the hierarchicalMenu constant in place of the nokey constant. A 
menu item can have either a keyboard equivalent or submenu defined for it, but not 
both. To indicate that a menu item has an icon that is defined in an 'SICN" resource, 
specify $1E in place of the nokey constant. To indicate that a menu item has an icon that 
is defined in an 'ICON' resource and that the Menu Manager should reduce this icon to 
a 16-by-16 bit rectangle, specify $1D in place of the nokey constant. Menu items that 
have small icons or reduced icons cannot have keyboard equivalents. 


To set the script code of a menu item’s text, specify $1C in place of the nokey constant 
and define the desired script code in place of the noicon constant. If an item contains 
$1C in its keyboard equivalent field and a script code in its icon field, the Menu Manager 
draws the item’s text in the script identified by the script code value if the corresponding 
script system is installed. If you do not specify a script code for a menu item, the Menu 
Manager displays the menu item’s text in the system font of the current system script. 
For Roman scripts, the system font is Chicago and the system font size is 12. 


To assign a mark that appears to the left of the menu item text and to the left of any 

icon, specify the marking character in place of the nomark constant in your resource 
definition. If the menu item has a submenu, then specify the menu ID of the submenu in 
place of the nomark constant. Submenus of an application must use menu IDs from 

1 through 235; submenus of a desk accessory must use menu IDs from 236 through 255. 
Note that defining the menu ID of a submenu ina 'MENU' resource does not attach the 
submenu to its menu. You must use the Get Menu function and InsertMenu procedure 

to do this. “Creating a Hierarchical Menu,” which begins on page 3-53, gives information 
on attaching a submenu to its menu. 








To assign a font style to a menu item, in your 'MENU' resource use the constants bold, 
italic, plain, outline, and shadow to get their corresponding styles. 


Listing 3-1 defines the second menu item as a divider. When you use a hyphen as the 
first character in the string that defines the text of a menu item, the Menu Manager 
creates a divider that extends across the entire width of the menu item. You cannot 
assign any other characteristics to a divider. 


The 'MENU' resource for the Apple menu does not list any other menu items. Use the 
AppendResMenu procedure to add the desktop items to the Apple menu after your 
application creates the menu. See “Adding Items to the Apple Menu” on page 3-68 for 
more information. 


Once you create a menu, you can append additional items to it using the AppendMenu, 
InsertMenulItem, InsertResMenu, or AppendResMenu procedure. You can also 
change the characteristics of individual menu items using Menu Manager routines. See 
“Changing the Appearance of Items in a Menu” on page 3-57 for more information. 
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Figure 3-12 on page 3-24 shows a typical Edit menu for an application. Listing 3-2 shows 
a 'MENU' resource for this Edit menu. 





Listing 3-2 Rez input fora 'MENU' resource for an Edit menu 


#define mEdit 130 





resource 'MENU' (mEdit, preload) { /*resource ID, preload resource*/ 
mEdit, /*menu ID*/ 
textMenuProc, /*uses standard menu definition */ 


/* procedure*/ 
/*enable/disable first 31 menu */ 


/* items as appropriate*/ 


0b0000000000000000001001000000000, 


enabled, /*xenable title*/ 
"Edit", /*text of menu title*/ 
{ /*menu items*/ 
"Undo", noicon, "Z", nomark, plain; /*keyboard equivalent Command-Z*/ 
ae noicon, nokey, nomark, plain; 
"Gut", noicon, "X", nomark, plain; /*keyboard equivalent Command-X*/ 
"Copy", noicon, "C", nomark, plain; /*keyboard equivalent Command-C*/ 
"Paste", noicon, "V", nomark, plain; /*keyboard equivalent Command-V*/ 
"Clear", noicon, nokey, nomark, plain; 
"Select All", 
noicon, "A", nomark, plain; /*keyboard equivalent Command-A*/ 
ge noicon, nokey, nomark, plain; 
"Create Publisher...", 
noicon, nokey, nomark, plain; 
"Subscribe To...", 
noicon, nokey, nomark, plain; 
"Publisher Options...", 
noicon, nokey, nomark, plain; 
WSMy noicon, nokey, nomark, plain; 
"Show Clipboard", 
noicon, nokey, nomark, plain 


hi 


3-48 


Listing 3-2 defines the resource ID of the Edit menu as 130, defines the menu ID of the 
Edit menu as 130, and specifies that this menu uses the standard menu definition 
procedure. The listing defines the initial enabled state of the first 31 menu items and 
also specifies that the menu title should be enabled when it is first created. 


The resource listing defines the title of the menu, Edit. It then defines the characteristics 
of each menu item in the menu. For each menu item, you need to specify the text of the 
menu item and any other characteristics of the menu item. For example, Listing 3-2 
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defines the first item in the Edit menu as the Undo command with these characteristics: 
there is no icon to the left of the menu item text, the menu item has a keyboard 
equivalent of Command-Z, it does not have any mark to the left of the menu item text, 
and the style of the menu item text is plain. The listing defines the second menu item as 
a divider line. It defines the Cut, Copy, and Paste commands; specifies keyboard 
equivalents for each of them; and defines the rest of the items in the menu. 


Listing 3-3 shows another example of a resource description of a menu, the File menu of 
a typical application. 





Listing 3-3 Rez input fora 'MENU' resource for a File menu 





resource 'MENU' (mFile, preload) { 
mFile, textMenuProc, 
0b0000000000000000000010000000000, 


enabled, 

"File", 

{ 
"New", noicon, "N", nomark, plain; 
"OpPene" 7 noicon, "O", nomark, plain; 
A easier noicon, nokey, nomark, plain; 
"Close", noicon, "W", nomark, plain; 
"Save", noicon, "S", nomark, plain; 
"Save As...", noicon, nokey, nomark, plain; 
Sama noicon, nokey, nomark, plain; 


"Page Setup..", noicon, nokey, nomark, plain; 


"Print...", noLeon,;: "PB", nomark, plain; 
Ny noicon, nokey, nomark, plain; 
“OULE ",, noicon;: "QO"; nomark, plain 


hi 


Creating a Menu Bar Resource 


You typically define your application’s menu bar using a menu bar ('MBAR") resource. 
Listing 3-4 shows an 'MBAR' resource, in Rez format, for a sample application. 





Listing 3-4 Rez input for an "MBAR" resource 
#define rMenuBar 128 
#define mApple 128 
#define mFile 129 
#define mEdit 130 
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resource 'MBAR' (rMenuBar, preload) {/*resource ID, preload*/ 
/*menus appear in the order listed here*/ 





{ mApple, mFile, mEdit }; /*resource IDs for menus in */ 
/* this menu bar*/ 
}; 


Listing 3-4 defines the 'MBAR"' resource with resource ID 128. This 'MBAR' resource 
defines the order and resource IDs of the menus contained in it; it defines its first 
three menus as the menus with resource IDs 128, 129, and 130. The Menu Manager 
uses the assigned resource IDs to read in the menus when it creates a menu bar from 
an 'MBAR' resource. 


Setting Up Your Application’s Menu Bar 





To create a menu list as defined in an 'MBAR" resource, use the Get NewMBar function. 
For each menu defined by the 'MBAR' resource, the Get NewMBar function creates a 
menu record for the menu, creates each menu according to its resource definition in its 
corresponding 'MENU' resource, and inserts each menu into the new menu list. The 
GetNewMBar function returns a handle to the created menu list. For example, this code 
creates a menu list for the menu bar defined by the 'MBAR"' resource with resource ID 
128 (defined by the constant rMenuBar): 











CONST 
rMenuBar = 128; 
VAR 
menuBar: Handle; 
menuBar := GetNewMBar(rMenuBar); {read menus and menu bar } 





{ descriptions,create & return } 
{ a handle to a new menu list} 


Use the SetMenuBar procedure to set the current menu list to the menu list created 
by your application and the DrawMenuBar procedure to update the menu bar’s 
appearance. For example, Listing 3-5 uses these two routines to set up the application’s 
menu bar. 


Listing 3-5 Setting up an application’s menus and menu bar 


PROCEDURE MyMakeMenus; 
VAR 
menuBar: Handle; 

BEGIN 

{first use the GetNewMBar function to read menus in & create a } 





{ new menu list. If you define an Apple menu, the Menu Manager } 
{ inserts the Help and Application menus (and Keyboard menu if } 


{ necessary) into the newly created menu list} 
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menuBar := GetNewMBar (rMenuBar) ; 
IF menuBar = NIL THEN 
EXIT (MyMakeMenus) 


SetMenuBar(menuBar); {insert menus into the current menu list} 








, 


DisposHandle (menuBar) ; 
{add desktop items in Apple Menu Items } 
{ folder to Apple menu} 

AppendResMenu (GetMenuHandle (mApple), 'DRVR'); 








MyAdjustMenus; {adjust items and enabled state of menus} 
DrawMenuBar; {draw the menu bar} 
END; 


The code in Listing 3-5 creates the application’s menu bar by reading in the definition 
from the 'MBAR"' resource with resource ID 128, and it uses SetMenuBar to set the 
current menu list to the newly created menu list. The code then adds the desktop 
items in the Apple Menu Items folder to the Apple menu using the AppendResMenu 
procedure. 


You can use the GetMenuHand1e function to get a handle to the menu record of 

any menu in the current menu list. You supply the menu ID of the desired menu as a 
parameter to GetMenuHandle, and GetMenuHandle returns a handle to the menu’s 
menu record. Most Menu Manager routines require either a menu ID ora handle to 

a menu record as a parameter. 


After creating the menu bar and adding any other menus or items as necessary, the code 
calls the MyAdjustMenus procedure to adjust the application’s menus—for example, 
this procedure sets the enabled and disabled states of menu items in accordance with the 
current state of the application. (Listing 3-19 on page 3-74 shows the application-defined 
MyAdjustMenus procedure used in Listing 3-5.) After adjusting the menus, the code in 
Listing 3-5 uses DrawMenuBar to draw the menus in the menu bar according to their 
current enabled state and as they are defined in the current menu list. 





Usually you'll define the menus of your application and its menu bar using 'MENU' 
resources and an 'MBAR" resource and using the Get NewMBar function to read the 
resource definitions. However, you can choose to read ina 'MENU' resource using the 
GetMenu function or to create anew empty menu using NewMenu. You can then insert 

a menu into the current menu list using the InsertMenu procedure. See “Creating 
Menus” on page 3-105 and “Adding Menus to and Removing Menus From the Current 
Menu List” on page 3-108 for information on forming your menus using these routines. 








If your application uses a submenu, you need to use the Get Menu function and 
InsertMenu procedure to make these menus available to your application. See 
“Creating a Hierarchical Menu” on page 3-53 for information on creating submenus. 
If your application uses a pop-up menu, you can use the pop-up control definition 
function and Dialog Manager or Control Manager routines to create and display 

the pop-up menu. See “Creating a Pop-Up Menu” on page 3-56 for information on 
creating pop-up menus. 
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The Menu Manager creates and initializes your application’s menu color information 
table when your application calls Get NewMBar. You can add entries to your 
application’s menu color information table if you want to use colors other than the 
default colors in your menus and menu bar. You can add entries to this table by 
providing menu color information table ('mctb") resources or by using the 
SetMCEntries procedure. Usually you should use the default colors to help maintain 
a consistent user interface. 


If you add menu color entries to your application’s menu color information table and 
your application uses more than one menu bar, you need to save a copy of your 
application’s menu color information table before changing menu bars. Use the 
GetMCInfo function before calling Get NewMBar and call SetMCInfo afterward to 
restore the menu color information table. Listing 3-6 shows a routine that saves and 
then restores the menu color information table when creating a new menu bar. 


Listing 3-6 Saving and restoring menu color information 


PROCEDURE MyChangeMenuBarAndSaveColoriInfo; 








CONST 
rMenuBar2 = 129; 

VAR 
menu: MenuHandle; 
menuBar: Handle; 
currentMCTable: MCTableHandle; 
newMCTable: MCTableHandle; 

BEGIN 

currentMCTable := GetMCInfo; {save menu color info table} 





IF currentMCTable = NIL THEN 
EXIT (MyChangeMenuBarAndSaveColoriInfo) ; 
menuBar := GetNewMBar (rMenuBar2);{read menus in & create new menu list} 
IF menuBar = NIL THEN 
EXIT (MyChangeMenuBarAndSaveColoriInfo) ; 
newMCTable := GetMCInfo; {get new menu color info table} 
IF newMCTable = NIL THEN 
EXIT (MyChangeMenuBarAndSaveColoriInfo) ; 
SetMCInfo(currentMCTable) ; {restore previous menu color info table} 


Gl 











SetMenuBar (menuBar) ; {insert menus into the current menu list} 
DisposHandle (menuBar) ; 
AppendResMenu (GetMenuHandle(m2Apple), 'DRVR'); {add desktop items from } 

{ Apple Menu Items folder to Apple menu} 








MyAdjustMenus; {adjust menu items} 
DrawMenuBar; {draw the menu bar} 
END; 
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Creating a Hierarchical Menu 


A hierarchical menu is a menu that has a submenu attached to one or more of its menu 
items. Submenus can be useful when your application needs to offer additional choices 
to the user without taking up extra space in the menu bar. If you use a submenu in your 
application, use it to give the user additional choices or to choose attributes, not 
additional commands. 


A menu item of a pull-down menu is the title of the attached submenu. A menu item 
that has a triangle facing right in the location of the keyboard equivalent identifies 
that a submenu is attached to the menu item. The title of a submenu should represent 
the choices it contains. Figure 3-32 shows a menu with a submenu whose menu title is 
Label Style. 


Figure 3-32 A menu item with a submenu 
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When a user drags the cursor through a menu and rests it on a menu item with a 
submenu attached to it, the Menu Manager displays the submenu after a brief delay. 
The title of the submenu remains highlighted while the user browses through the 
submenu; the Menu Manager unhighlights the menu title of the submenu when the 
user releases the mouse button. 


Your application is responsible for placing any marks next to the current choice or 
attribute of the submenu. For example, in Figure 3-32 the application placed the 
checkmark next to the Numeric menu item to indicate the current choice. If the user 
makes a new choice from the menu, your application should update the menu items 
accordingly. 


You can specify that a particular menu item has a submenu by identifying this 
characteristic (using the hierarchicalMenu constant) when you define the menu item 
in its 'MENU' resource. You cannot assign keyboard equivalents to a menu item that has 
a submenu. (You can define keyboard equivalents for the menu items in the submenu, 
but this is not recommended.) You identify the menu ID of the submenu in place of the 
marking character in the menu item’s resource description. Thus, a menu item that has a 
submenu cannot have a marking character and cannot have a keyboard equivalent. 
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To insert a submenu into the current menu list, you must use the InsertMenu 
procedure. The Get NewMBar function does not read in the resource descriptions of 
any submenus. 


Listing 3-7 shows the 'MENU' resource for an application-defined menu called Outline. 
The Outline menu contains a number of menu items, including the Label Style menu 
item. The description of this menu item contains the constant hierarchicalMenu, 
which indicates that the item has a submenu. This menu item description also contains 
the menu ID of the submenu (defined by the mSubMenu constant). The menu ID of a 
submenu of an application must be from 1 through 235; the menu ID of a submenu of a 
desk accessory must be from 236 through 255. 


The submenu is defined by the menu with the menu ID specified by the Label Style 
menu item. You define the menu items of a submenu in the same way as you would a 
pull-down menu (except you shouldn’t define keyboard equivalents for items ina 
submenu, and you shouldn’t attach a submenu to another submenu). 


Listing 3-7 Rez input for a description of a hierarchical menu with a submenu 


#define mOutline 135 
#define mSubMenu 181 


resource 'MENU' (mOutline, preload) { 








mOutline , /*menu ID*/ 

textMenuProc, 

0b0000000000000000000000000010000, 

enabled, 

"Outline", /*menu title*/ 

{ /*menu items*/ 
"Expand", noi:con,. "E", nomark, plain; 
"Expand To...", noicon, nokey, nomark, plain; 
"Expand All", noicon, nokey, nomark, plain; 
"Collapse", noicon, nokey, nomark, plain; 
Sey noicon, nokey, nomark, plain; 


/*the Label Style item has a submenu with menu ID mSubMenu*/ 


"Label Style", noicon, hierarchicalMenu, mSubMenu, plain; 
Mons noicon, nokey, nomark, plain; 
"Move Left", noicon, "L", nomark, plain; 
"Move Right", noicon, "R", nomark, plain; 
"Move Up", noicon, "U", nomark, plain; 
"Move Down", noicon, "D", nomark, plain 


hi 
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resource 'MENU' (mSubMenu , preload) { 








mSubMenu , /*menu ID*/ 
textMenuProc, 
0b0000000000000000000000001111111, 
enabled, 
"Label Style", /*menu title (ignored--defined */ 
/* by parent menu item text) */ 
{ /*menu items*/ 
"Alphabetic", noicon, nokey, nomark, plain; 
"Bullet", noicon, nokey, nomark, plain; 
"Chicago", noicon, nokey, nomark, plain; 
"Harvard", noicon, nokey, nomark, plain; 
"Legal", noicon, nokey, nomark, plain; 
"Numeric", noicon, nokey, nomark, plain; 
"Roman", noicon, nokey, nomark, plain 


}; 


When you use Get NewMBar to read in menu descriptions and create a new menu list, 
GetNewMBar records the menu ID of any submenu in the menu record but does not read 
in the description of the submenu. To read a description of a submenu, use the Get Menu 
function. To actually insert a submenu into the current menu list, you must use the 
InsertMenu procedure. 


When needed, your application can use the GetMenu function to read a description of 
the characteristics of a menu from a 'MENU' resource. The Get Menu function creates a 
menu record for the menu, allocating space for the menu record in your application’s 
heap. The GetMenu function creates the menu and menu items (and fills in the menu 
record) according to its 'MENU' resource. The GetMenu function does not insert the 
menu into a menu list. When you’re ready to add it to the current menu list, use the 
InsertMenu procedure. 


Listing 3-8 uses the Get Menu function to read the description of a submenu and uses the 
InsertMenu procedure to insert the menu into the current menu list. 


Listing 3-8 Creating a hierarchical menu 





PROCEDURE MyMakeSubMenu (subMenuResID: Integer) ; 


VAR 
subMenu: MenuHandle; 
BEGIN 
subMenu := GetMenu(subMenuResID) ; 


InsertMenu (subMenu, -1); 
END; 
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To insert a submenu into the current menu list using the InsertMenu procedure, 
specify —1 in the second parameter to insert the menu into the submenu portion of the 
menu list. As the user traverses menu items, if a menu item has a submenu the 
MenuSelect function looks in the submenu portion of the menu list for the submenu; it 
searches for a menu with a defined menu ID that matches the menu ID specified by the 
hierarchical menu item. If it finds a menu with a matching menu ID, it attaches the 
submenu to the menu item and allows the user to browse through the submenu. 


Creating a Pop-Up Menu 


In System 7, pop-up menus are implemented as controls. You define the menu items of a 
pop-up menu in the same way as in other menus (using a 'MENU' resource), and you 
define specific features of the pop-up menu itself (such as the location of the pop-up 
menu) in a control that uses the standard pop-up control definition function. Pop-up 
menus provide the user with a simple way to select from among a list of choices without 
having to move up to the menu bar. They are particularly useful in a dialog box that 
requires the user to specify a number of settings or values. Figure 3-33 shows an example 
of a pop-up menu in a dialog box. 





Figure 3-33 A pop-up menu in a dialog box 
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To create a pop-up menu, create a control that uses the pop-up control definition 
function, define the pop-up menu and its menu items, and associate the control with a 
window or dialog box. You can use Dialog Manager or Control Manager routines to 
display pop-up menus. 


For example, if you define a modal dialog box that contains a pop-up control and use the 
Dialog Manager to display and help handle events in the dialog box, the Dialog Manager 
automatically uses the pop-up control definition function to draw the control and also to 
handle user interaction when the user presses the mouse button while the cursor is over 
a pop-up control. 


If your application defines a control in one of your application’s windows, you can use 
TrackControl and other Control Manager routines to handle the pop-up menu. 


The pop-up control definition function draws a box around the pop-up box, draws the 
drop shadow, inserts the text into the pop-up box, draws the downward-pointing 
triangle, and draws the pop-up title. When a dialog box contains a control that uses the 


Using the Menu Manager 


CHAPTER 3 


Menu Manager 


pop-up control definition function and the user presses the mouse button while the 
cursor is in the pop-up control, the pop-up control definition function highlights the 
pop-up menu title, displays the pop-up menu, and handles all user interaction until the 
user releases the mouse button. When the user releases the mouse button, the pop-up 
control definition function closes the pop-up box, draws the user’s choice in the pop-up 
box (or restores the previous item if the user did not make a new choice), stores the 
user’s choice as the value of the control, and unhighlights the pop-up menu title. Your 
application can use the Control Manager function Get Cont rolValue to get the value 
of the control and to determine the currently selected item in the pop-up menu. 


To create a pop-up control, create a control and specify that the control uses the pop-up 
control definition function by specifying the popupMenuP roc constant: 


CONST popupMenuProc = 1008; {pop-up menu control} 


If you specify popupMenuProc (plus any appropriate variation code) as the procID 
field of the resource description of a control, when your application creates the control 
(by using the Dialog Manager or by using Get NewCont rol) the Control Manager 
creates the pop-up control, which includes the pop-up title and the pop-up box with a 
one-pixel drop shadow. The appearance of the pop-up title and the values in the menu 
are controlled by other values stored in the resource (or other parameters passed to 
NewCont rol). See the chapter “Control Manager” in this book for information on 
the NewControl function. 


If your application does not use the standard pop-up control definition function, you 
can create your own control definition function to implement pop-up menus. In this 
case you can use the PopUpMenuSelect function to draw the pop-up menu and track 
the cursor within the menu. Your application is responsible for highlighting the title of 
the pop-up menu before calling PopUpMenuSelect and unhighlighting the title 
afterward (to duplicate the behavior of menu titles in the menu bar). Your application 
must also set the mark of the items in the pop-up menu as appropriate if you use the 
PopUpMenuSelect function. 


For more information on creating controls, see the chapter “Control Manager” in this 
book. For listings that define the dialog box shown in Figure 3-33, see the chapter 
“Dialog Manager” in this book. 


Changing the Appearance of Items in a Menu 


You can change the appearance of an item in a menu using Menu Manager routines. For 
example, you can change the font style, text, or other characteristics of menu items. You 
can also enable or disable a menu item. 


Most of the Menu Manager routines that get or set characteristics of a particular menu 
item require three parameters: 


m ahandle to the menu record of the menu containing the desired menu item 
m the number of the menu item 


m a variable that either specifies the data to set or identifies where to return information 
about that item 
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Enabling and Disabling Menu Items 





Using the EnableItem and DisableItem procedures, you can enable and disable 
specific menu items or an entire menu. You pass as parameters to these two procedures a 
handle to the menu record that identifies the desired menu and either an item number 
that identifies the particular menu item to enable or disable or a value of 0 to indicate 
that the entire menu should be enabled or disabled. 


Your application should always enable and disable any menu items as appropriate— 
according to the user’s content—before calling MenuSelect orMenuKey. For example, 
you should enable the Paste command when the scrap contains data that the user can 
paste. (Listing 3-19 on page 3-74 shows code that adjusts an application’s menus.) 








When you disable or enable an entire menu, call DrawMenuBar to update the menu bar. 
The DrawMenuBar procedure draws the menus in the menu bar according to their 
current enabled state and as they are defined in the current menu list. 


If you disable an entire menu, the Menu Manager dims the menu title at your 
application’s next call to DrawMenuBar and dims all items in the menu when it displays 
the menu. If you enable an entire menu, the Menu Manager enables only the menu title 
and any items that you did not previously disable individually; the Menu Manager does 
not enable any item that your application previously disabled by calling DisableItem 
with that menu item’s item number. For example, if all items in your application’s Edit 
menu are enabled, you can disable the Cut and Copy commands individually using 
DisableItem. If you choose to disable the entire menu by passing 0 as the menu item 
parameter to DisableItem, the menu and all its items are disabled. If you then enable 
the entire menu by passing 0 as the menu item parameter to EnableItem, the menu and 
its items are enabled, except for the Cut and Copy commands, which remain disabled. In 
this case, to enable the Cut and Copy commands, you must enable each one individually 
using EnableItem. 


You can use DisableItem to disable items that aren’t appropriate at a given time. For 
example, you can disable the Cut and Copy commands when the user has not selected 
anything to cut or copy and disable the Paste command when the scrap is empty. 


This code enables the File menu, disables the Cut and Copy commands in the Edit menu, 
and disables the application-defined menu Colors. 


VAR 
menu: MenuHandle; 





menu := GetMenuHandle(mFile); {get a handle to the File menu} 
EnableItem(menu, 0); {enable File menu and any items } 
{ not individually disabled} 








DrawMenuBar; {update menu bar's appearance} 
menu := GetMenuHandle(mEdit); {get a handle to the Edit menu} 
DisableItem(menu, iCut); {disable the Cut command} 
DisableItem(menu, iCopy); {disable the Copy command} 
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menu := GetMenuHandle(mColors);{get a handle to Colors menu} 
DisableItem(menu, 0); {disable Colors menu & all } 
{ items in it} 





DrawMenuBar; {update menu bar's appearance} 


If you disable or enable an entire menu, call DrawMenuBar when you need to update the 
menu bar’s appearance. If you do not need to update the menu bar immediately, you can 
use the InvalMenuBar procedure instead of DrawMenuBar, thus reducing flickering in 
the menu bar. Rather than drawing the menu bar twice as in the previous example, you 
can use InvalMenuBar instead of DrawMenuBar, causing the Event Manager to redraw 
the menu bar the next time it scans for update events. The InvalMenuBar procedure is 
available in System 7 and later. See page 3-114 for additional details on the 
InvalMenuBar procedure. 








Changing the Text of an Item 
You can get or set the text of a menu item using Menu Manager routines. 


To get the text of a menu item, use the GetMenuItemText procedure. For example, you 
can use the GetMenuItemText procedure to get the text of a menu item that you added 
to amenu using InsertResMenu or AppendResMenu 


To set the text of a menu item, use the SetMenuItemText procedure. You can use 

the SetMenuItemText procedure as a convenient way to change the text of a menu 
command that allows the user to toggle between two states. For example, if your 
application has a menu command that allows the user to either show or hide the 
Clipboard window, depending on whether the window is currently showing, you can 
change the text of the menu item at the appropriate time using the SetMenuItemText 
procedure. 


Listing 3-9 changes the text of a menu item from Hide Clipboard to Show Clipboard or 
vice versa, based on the state of an application-defined global variable (gToggleState) 
that holds the state information. 


Listing 3-9 Changing the text of a menu item 


PROCEDURE MyToggleHideShow; 


£3 

















VAR 
myMenu: MenuHandle; 
item: Integer; 
itemString: Str255; 
BEGIN 
myMenu := GetMenuHandle (mEdit) ; 
item := iToggleHideShow; 
IF gToggleState = kShow THEN 
BEGIN 
GetIndString(itemString, kMyStrings, kShowClipboard) ; 
gToggleState := kHide; 
END 
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ELSE 
BEGIN 
GetIndString(itemString, kMyStrings, kHideClipboard) ; 
gToggleState := kShow; 
END; 
SetMenulItemText (myMenu, item, itemString); 
END; 


Note that if you use the SetMenuItemText procedure, you should define the text of the 
menu item in a string resource or string list resource (for example, using an 'STR_ ' or 
'STR#' resource). This makes your application easier to localize. 


Changing the Font Style of Menu Items 


You can change or get the font style of a menu item using the Set ItemStyle or 

Get ItemStyle procedure. To set the style of a menu item, specify a handle to the menu 
record of the menu containing the menu item whose style you want to set, specify the 
number of the menu item to set, and specify the desired style. 


You specify the style using values from the set defined by the Style data type: 


TYPE 





StyleItem = (bold, italic, underline, outline, shadow, 
condense, extend); 
Style = SET OF StyleItem; 


You can set the style of a menu item to zero, one, or more than one of the styles defined 
by the StyleItem data type. You can set the style of a menu item to the empty set to 
obtain the plain font style. 


Listing 3-10 shows code that sets the style of menu items listed in an application’s 
Style menu. 


Listing 3-10 Setting the font style of menu items 


VAR 
menu: MenuHandle; 
itemStyle: Style; 





menu := GetMenuHandle(mStyle); {get a handle to the Style menu} 
itemStyle := [italic]; 

SetItemStyle(menu, ilItalic, itemStyle);{set to italic style} 
itemStyle := [bold]; 

SetItemStyle(menu, iBold, itemStyle);{set item to bold style} 
itemStyle := [bold, Italic]; 

SetItemStyle(menu, iBoldItal, itemStyle); {bold & italic style} 
itemStyle := []; 


SetItemStyle(menu, iPlain, itemStyle);{set item to plain style} 








To get the style of a menu item, you can use the Get ItemSt yle procedure. 
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Changing the Mark of Menu Items 


You can change or get the mark of a menu item using the Set ItemMark or 
Get ItemMark procedure. To set the mark of a menu item to a checkmark, you 
can use either the CheckItem or the Set ItemMark procedure. 


To set the mark of a menu item, specify a handle to the menu record of the menu 
containing the item whose mark you want to set, specify the number of the menu 
item to set, and specify the mark to use as the marking character of the menu item. 


You typically use checkmarks and dashes in menus that contain commands that set 
attributes and that you have grouped in accumulating groups. For example, you use a 
combination of checkmarks and dashes in the Style menu to indicate whether the 
selection contains more than one style. Figure 3-8 on page 3-15 shows an example of 
using checkmarks and dashes in a menu. “Groups of Menu Items” beginning on 

page 3-14 gives guidelines for determining how to group your menu items. 


You specify the mark of the menu item by passing a character as one of the parameters to 
the Set ItemMark procedure. You should use only the standard marking characters, 
such as the checkmark, diamond, or dash, in your menu items; avoid using other marks 
that might confuse the user. You can use the constants listed here to specify that the item 
has no mark or to set the marking character to a checkmark or diamond: 


CONST noMark = 0; {no marking character} 
checkMark S125 {checkmark } 
diamondMark = $13; {diamond symbol} 


As another example of the use of marks in menus, Listing 3-11 shows code that sets the 
mark of items in an application-defined Directory menu. It sets the marking character of 
the menu item of the last directory accessed to a checkmark, sets the marking character 
of the second-last directory accessed to the diamond mark, and removes the mark from 
the third-last directory accessed. 


Listing 3-11 Adding marks to and removing marks from menu items 


VAR 
menu: MenuHandle; 
itemMark: Char; 
{get handle to Directory menu} 
menu := GetMenuHandle(mDirectory) ; 
itemMark := CHR(checkMark) ; 


SetItemMark(menu, gLastDir, itemMark); {set mark to checkmark} 


itemMark := CHR(diamondMark) ; 
SetItemMark(menu, gOldLastDir, itemMark); {set mark to diamond} 











itemMark := CHR(noMark) ; 
SetItemMark (menu, gSecondLastDir, itemMark);{remove any mark} 
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You can also set the mark of a menu item to a checkmark using the CheckItem 
procedure: 


VAR 
menu: MenuHandle; 
{get handle to Directory menu} 
menu := GetMenuHandle(mDirectory) ; 
CheckItem(menu, gLastDir, TRUE); {set to checkmark} 








CheckItem(menu, gSecondLastDir, FALSE); {remove checkmark or } 
{ any other mark} 


Changing the Icon or Script Code of Menu Items 


You can change or get the icon of a menu item using the Set ItemIcon or 
Get ItemIcon procedure. You can also use these procedures to get or set the 
script code of a menu item’s text. 


To set the script code of a menu item using the Set ItemIcon procedure, you need to 


m specify a handle to the menu record of the menu containing the item whose script 
code you want to set 


m specify the number of the menu item to set 
m specify the script code 


To set a menu item’s script code, you must also define the keyboard equivalent field of 
the item to $1C. If an item contains $1C in its keyboard equivalent field and a script code 
in its icon field, the Menu Manager draws the item in the script identified by the script 
code value if the corresponding script system is installed. 


To set the icon of a menu item using the Set ItemIcon procedure, you need to 


m specify a handle to the menu record of the menu containing the item whose icon you 
want to set 


m specify the number of the menu item to set 


m specify the icon number (the Menu Manager uses the icon number to generate the 
resource ID of the icon) 
The icon number that you specify to Set ItemIcon must be a value from 1 through 255 
for color icons or icons, from 1 through 254 for small icons and reduced icons, or 0 to 
specify that the item doesn’t have an icon. The Menu Manager adds 256 to the number 
you specify and uses this calculated number as the icon’s resource ID. For example, if 
you specify the icon number as 5, the Menu Manager uses the Resource Manager to find 
the icon with resource ID 261. The Menu Manager first looks for an icon resource of type 
'cicn'; if it can’t find one with the calculated resource ID number (or if the computer 
doesn’t have Color QuickDraw), it looks for a resource of type 'SICN' if the keyboard 
equivalent field contains $1E; otherwise, it looks for an 'ICON' resource. 


Use either an 'ICON' or 'SICN"' resource if you want to provide only a black-and-white 
icon. In addition, provide a 'cicn' resource if you want the Menu Manager to use a 
color icon when Color QuickDraw is available. Figure 3-34 shows examples of icons ina 
menu item generated from icon resources: an 'SICN' resource, an ' ICON" resource, an 
"ICON" resource reduced to fit in a 16-by-16 bit rectangle, anda 'cicn' resource. 
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Figure 3-34 Icons in menu items 
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The Menu Manager automatically fits the icon in the menu item according to your 
specifications. If the Menu Manager uses a 'cicn' resource, it automatically enlarges 
the enclosing rectangle of the menu item according to the rectangle specified in the 
"cicn' resource. If the Menu Manager uses an 'ICON' resource and the item specifies 
the nokey constant as the keyboard equivalent, the Menu Manager enlarges the 
rectangle of the menu item to fit the 32-by-32 bit 'ICON' resource. You can request that 
the Menu Manager reduce an 'ICON' resource to the size of a 16-by-16 bit small icon by 
specifying a value of $1D as the item’s keyboard equivalent. To request that the Menu 
Manager use an 'SICN' resource instead of an 'ICON' resource, specify a value of $1E 
as the item’s keyboard equivalent. 


This code sets the icon of a menu item to a specified icon. 


VAR 
menu: MenuHandle; 
itemIcon: Byte; 
itemIcon := 5; 
menu := GetMenuHandle (mWeather) ; 


{set the icon for this item in the Weather menu} 
SetItemIcon(menu, iBeachWeather, itemIcon); 





Listing 3-12 shows the Rez description of three menu items, each of which contains 
icons. The first menu item has an icon with resource ID 261 (5 plus 256) and is defined by 
a resource type of either 'cicn' or 'ICON'. The second menu item has an icon with 
resource ID 262 (6 plus 256) and is identified by either a 'cicn' resource oran 'ICON' 
resource; however, in this case, the value of $1D requests the Menu Manager to reduce 
the 'ICON' resource to a small icon. The third menu item has an icon with resource ID 
263 (7 plus 256) and is defined by either a 'cicn' resource or an 'SICN" resource. 


Listing 3-12 Specifying icons for menu items 





#define mWeather 138 

resource 'MENU' (mWeather, preload) { 
mWeather, 
textMenuProc, 
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0b0000000000000000001011101100111, 
enabled, “Weather", 
{ 





"Beach Weather", /*item has icon or color icon */ 
/* with icon number 5*/ 
5, nokey, nomark, plain; 
"Ski Weather", /*item has reduced icon or color */ 
/* icon with icon number 6*/ 
6, $1D, nomark, plain; 
"Kite-Flying Weather",/*item has small icon or */ 


/* color icon with icon number 7*/ 





7, S1E, nomark, plain 


hi 


See the chapter “Finder Interface” in this book for details on how to create icons. 


Adding Items to a Menu 


Usually you define a menu and all its items ina 'MENU' resource. Occasionally you 
might need to add items to a menu after you’ve created it. After creating a menu (using 
NewMenu, GetMenu, or GetNewMBar), you can add items to it using the AppendMenu, 
InsertMenulItem, AppendResMenu, or InsertResMenu procedure. 





You can use AppendResMenu or InsertResMenu to add items that consist of resource 
names to a menu. For example, you can use the AppendResMenu procedure to add fonts 
to your application’s Font menu or to add all of the desktop items from the Apple Menu 
Items folder to your application’s Apple menu. These are common instances when you'll 
need to add items not already defined in a 'MENU' resource to a menu. See “Adding 
Fonts to a Menu” on page 3-69 and “Adding Items to the Apple Menu” on page 3-68 for 
information on adding names of resources to menus. 


If you add items to your application’s Help menu, you'll need to use AppendMenu or 
InsertMenulItem to add the additional items. This section discusses how to add items 
using the AppendMenu and InsertMenuItem procedures, and “Adding Items to the 
Help Menu” on page 3-67 shows a specific example of adding items to the Help menu. 


If you need to add items other than the names of resources to a previously created menu, 
you can use the AppendMenu or InsertMenuItem procedure. You can use 

AppendMenu to add items to the end of a menu; note that you can add items to only the 
end of the menu when using AppendMenu. Use InsertMenuItem to add items after 
any given item ina menu. When you add items to a menu using AppendMenu or 
InsertMenuItem, you can specify the same characteristics for menu items that are 
available to you when defining 'MENU' resources. 





Using the Menu Manager 


CHAPTER 3 


Menu Manager 


You specify a handle to the menu record of the menu to which you want to add the item 
or items, and you specify a string describing the items to add as parameters to the 
AppendMenu or InsertMenuItem procedure. The string you pass to these procedures 
should consist of the text and any characteristics of the menu items. You can specify a 
hyphen as the menu item text to create a divider line. You can also use various 
metacharacters in the text string to separate menu items and to specify certain 
characteristics of the menu items. The metacharacters aren’t displayed in the menu. 


Here is a list of the metacharacters you can use in the text string that you specify to the 
AppendMenu or InsertMenuItem procedure: 


Metacharacter Description 
; or Return Separates menu items. 


x When followed by an icon number, defines the icon for the item. If the 
keyboard equivalent field contains $1C, this number is interpreted as 
a script code. 

! When followed by a character, defines the mark for the item. If the 
keyboard equivalent field contains $1B, this value is interpreted as 
the menu ID of a submenu of this menu item. 


< When followed by one or more of the characters B, I, U, O, and S, 
defines the character style of the item to Bold, Italic, Underline, 
Outline, or Shadow, respectively. 


/ When followed by a character, defines the keyboard equivalent for 
the item. When followed by $1B, specifies that this menu item has a 
submenu. To specify that the menu item has a script code, small icon, 
or reduced icon, use the Set ItemCmd procedure to set the keyboard 
equivalent field to $1C, $1D, or $1E, respectively. 


( Defines the menu item as disabled. 


You can specify any, all, or none of these metacharacters in the text string to define the 
characteristics of a menu item. Note that the metacharacters that you specify aren’t 
displayed in the menu item. (To use any of these metacharacters in the text of a menu 
item, first use AppendMenu or InsertMenulItem, specifying at least one character as 
the item’s text. Then use the SetMenuItemText procedure to set the item’s text to the 
desired string.) 


Note 


If you add menu items using the AppendMenu or InsertMenuItem 
procedure, you should define the text and any marks or keyboard 
equivalents in resources for easier localization. 


Listing 3-13 shows a string list ('STR#') resource that stores the text of the menu items 
used in the next examples. 
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Listing 3-13 Rez input for text of menu items 





resource 'STR#' (300, "Text for appended menu items") { 
{ 
FR TLY*/ 
"Just Text"; 
LE L21* £ 
"Pick a Color..."; 
FELSY*7 
"(A2!=Everything<B/E"; 
} 
; 


Here’s code that uses the AppendMenu procedure to append a menu item with no 
specific characteristics other than its text to the menu identified by the menu handle in 
the myMenu variable. The text for the menu item is “Just Text” as stored in the 'STR#' 
resource with resource ID 300. 


VAR 
myMenu: MenuHandle; 
itemString: Str255; 


myMenu := GetMenuHandle(mLibrary) ; 
GetIndString(itemString, 300, 1); 
AppendMenu (myMenu, itemString); 


To insert an item after a given menu item, use the InsertMenuItem procedure. For 
example, this code inserts the menu item Pick a Color after the menu item with the item 
number specified by the iRed constant. The text for the new menu item consists of the 
string “Pick a Color...” as stored in the 'STR#' resource with resource ID 300. 


VAR 
myMenu: MenuHandle; 
itemString: Str255; 


myMenu := GetMenuHandle(mColors) ; 
GetIndString(itemString, 300, 2); 
InsertMenultem(myMenu, itemString, iRed); 





If you do not explicitly specify a value for an item characteristic in the text string that 
you pass to AppendMenu or InsertMenulItenm, the procedure assigns the default value 
for that characteristic. The Menu Manager defines the default item characteristics as no 
icon, no marking character, no keyboard equivalent, and plain text style. AppendMenu 
and InsertMenuItem enable the added menu items unless you specify otherwise. 


This code appends a menu item with the text “Everything” to the menu identified by the 
menu handle in the myMenu variable. The text and other characteristics of this menu 
item are stored in the 'STR#' resource shown in Listing 3-13. It also specifies that this 
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menu item is disabled, has an icon with resource ID 258 (2 + 256), and has the “=” 
character as a marking character; the style of the text is Bold; and the menu item has a 
keyboard equivalent of Command-E. 


VAR 
myMenu: MenuHandle; 
itemString: Str255; 


myMenu := GetMenuHandle(mLibrary) ; 
GetIndString(itemString, 300, 3); 
AppendMenu (myMenu, itemString); 


This code appends multiple items to the Edit menu using AppendMenu: 


VAR 
myMenu: MenuHandle; 





myMenu := GetMenuHandle (mEdit) ; 
AppendMenu (myMenu, 'Undo/Z;-;Cut/X;Copy/C;Paste/V'); 


The InsertMenuItem procedure differs from AppendMenu in how it handles the given 
text string when the text string specifies multiple items. The InsertMenuItem 
procedure inserts the items in the reverse of their order in the text string. For example, 
this code inserts menu items into the Edit menu using InsertMenuItemand is 
equivalent to the previous example: 


VAR 


myMenu: MenuHandle; 


myMenu := GetMenuHandle (mEdit) ; 
InsertMenuItem(myMenu, 'Paste/V';Copy/C;Cut/X;-;Undo/Z',0); 


Once you've added a menu item to a menu, you can change any of its characteristics 
using Menu Manager routines, as described in “Changing the Appearance of Items in a 
Menu” on page 3-57. 


Adding Items to the Help Menu 


You add items to the Help menu by using the HMGet He lpMenuHand1e function and 
either the AppendMenu or InsertMenuItem procedure. 


The HMGet HelpMenuHand_1e function returns a copy of the handle to the menu record 
of your application’s Help menu. Do not use the GetMenuHand_1e function to get a 
handle to the Help menu, because Get MenuHand1e returns a handle to the global Help 
menu, not the Help menu that is specific to your application. Once you have a handle to 
the Help menu that is specific to your application, you can add items to it using the 
AppendMenu procedure or other Menu Manager routines. For example, Listing 3-14 

adds the menu item displayed in Figure 3-19 on page 3-30. 
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Listing 3-14 Adding an item to the Help menu 





PROCEDURE MyAddHelpItem; 

















VAR 
myMenu: MenuHandle; 
myErr: OSErr; 
itemString: Str255; 
BEGIN 
myErr := HMGetHelpMenuHandle (myMenu) ; 











IF myErr = nokrr THEN 

IF myMenu <> NIL THEN 

BEGIN 
{get the string (with index kSurfHelp) from the 'STR#' } 
{ resource with resource ID kMyStrings} 
GetIndString(itemString, kMyStrings, kSurfHelp); 
AppendMenu (myMenu, itemString); 

END; 

END; 


When you add items to the Help menu, the Help Manager automatically adds a divider 
between the end of the standard Help menu items and your items. 


Be sure to use an 'hmnu' resource and specify the kHMHe1lpMenuID constant as the 
resource ID to provide help balloons for items you’ve added to the Help menu. (The 
Help Manager automatically creates the help balloons for the Help menu title and the 
standard Help menu items.) See the chapter “Help Manager” in Inside Macintosh: More 
Macintosh Toolbox for specific information on the 'hmnu' resource. 


The Help Manager automatically processes the event when a user chooses any of the 
standard menu items in the Help menu. The Help Manager automatically enables and 
disables help when the user chooses Show Balloons or Hide Balloons from the Help 
menu. The setting of Balloon Help is global and affects all applications. See “Handling 
the Help Menu” on page 3-81 for information on responding to the user when the user 
chooses one of your appended items. 


Adding Items to the Apple Menu 


To insert the items contained in the Apple Menu Items folder into your application’s 
Apple menu, use the AppendResMenu or InsertResMenu procedure and specify 
"DRVR' as the resource type. Doing so causes this procedure to automatically add all 
items in the Apple Menu Items folder to the specified menu. 


The user can place any desktop object in the Apple Menu Items folder. When the user 
places an item in this folder, the system software automatically adds it to the list of items 
in the Apple menu of all open applications. 
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After inserting the Apple menu into your application’s menu bar (by using Get NewMBar 
or GetMenu and InsertMenu), your application can add items to it. Listing 3-15 shows 
code that uses GetMenuHand_1e to get a handle to the application’s Apple menu. The 
code then uses the AppendResMenu procedure, specifying that AppendResMenu should 
add all desktop items in the Apple Menu Items folder to the application’s Apple menu. 


Listing 3-15 Adding menu items to the Apple menu 


VAR 
myMenu: MenuHandle; 


myMenu := GetMenuHandle(mApple) ; 
IF myMenu <> NIL THEN 
AppendResMenu (myMenu, 'DRVR');{add desktop items in the } 
{ Apple Menu Items folder } 
{ to the Apple menu} 


Listing 3-16 on page 3-70 shows a complete sample that sets up an application’s menu 
bar, adds items to the Apple menu, adds items to the Font menu, and then updates the 
appearance of the menu bar. 


Adding Fonts to a Menu 


If your application provides a Font menu, you typically include the description of the 
menu ina 'MENU' resource, include a description of your menu bar in an 'MBAR' 
resource, and use Get NewMBar to create your menu bar and all menus in the menu bar. 
Once you've created the menu, you can use AppendResMenu to add the names of all 
font resources in the Fonts folder of the System Folder (or in system software versions 
earlier than 7.1, in the System file) as menu items in your application’s Font menu. (You 
can also use Insert ResMenu to insert the fonts into your menu.) 








Listing 3-16 on the next page shows how to add names of font resources in the Fonts 
folder to an application’s Font menu. The AppendResMenu procedure adds all resources 
of the specified type to a given menu. If you specify the resource type 'FONT' or 

"FOND ', the Menu Manager adds all resources of type 'FOND' and 'FONT' to the 
menu. ('NFNT' and 'sfnt' resources are specified through 'FOND' resources.) 


The AppendResMenu and InsertResMenu procedures perform special processing for 
any font resources they find that have font numbers greater than $4000. The Menu 
Manager automatically sets the keyboard equivalent field of the menu item to $1C and 
stores the script code in the icon field of the menu item for any such 'FOND' resource. 
The Menu Manager displays a font name in its corresponding script if the script system 
for that font is installed. 
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Listing 3-16 Adding font names to a menu 














PROCEDURE MyMakeAl11Menus; 


VAR 
menu: MenuHandle; 
menuBar: Handle; 
BEGIN 
{read menus in & create new menu list} 
menuBar := GetNewMBar (rMenuBar) ; 





IF menuBar = NIL THEN 
EXIT (MyMakeAllMenus) ; 
SetMenuBar(menuBar); {insert menus into the current menu list} 








DisposHandle (menuBar) ; 





myMenu := GetMenuHandle(mApple) ; 
IF myMenu <> NIL THEN {add desktop items in } 
AppendResMenu (myMenu, 'DRVR'); { Apple Menu Items } 
{ folder to Apple menu} 
myMenu := GetMenuHandle(mFont) ; 
IF myMenu <> NIL THEN 
AppendResMenu (myMenu, 'FONT'); {add font names to the } 


{ Font menu--this adds all bitmapped and TrueType fonts } 
{ in the Fonts folder to the Font menu} 


MyAddHelpItem; {add app-specific item to Help menu} 
MyAdjustMenus; {adjust menu items} 
DrawMenuBar; {draw the menu bar} 

END; 


Your application should indicate the current font to the user by placing the appropriate 
mark next to the text of the menu item that lists the font name. (“Changing the Mark of 
Menu Items” on page 3-61 explains how to add marks to and remove marks from menu 
items; Figure 3-13 on page 3-26 and Figure 3-14 on page 3-27 show examples of typical 
Font menus.) 


If your application allows the user to change the font style or font size of text, you 
should provide separate Size and Style menus. See “Handling a Size Menu” beginning 
on page 3-82 for information on providing a Size menu in your application. 


Handling User Choice of a Menu Command 


If the user presses the mouse button while the cursor is in the menu bar, your application 
should first adjust its menus (enable or disable menu items and add marks to or remove 
marks from any items as appropriate to the user’s context) and then call the 
MenuSelect function to allow the user to choose a menu command. The MenuSelect 
function handles all user interaction until the user releases the mouse button and returns 
a value as its function result that indicates which (if any) menu item the user chose. 
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For a command with a keyboard equivalent, your application should allow the user to 
choose the command by pressing the keys that correspond to the keyboard equivalent 
of that menu command. If the user presses the Command key and another key, your 
application should adjust its menus and then call the MenuKey function to map this 
combination to a keyboard equivalent. The MenuKey function returns as its function 
result a value that indicates the corresponding menu and menu item of the keyboard 
equivalent. 


When the user chooses a menu command, your application should perform the action 
associated with that command. The MenuSelect and MenuKey functions highlight the 
menu title of the menu containing the chosen menu command. After your application 
performs any operation associated with the menu command chosen by the user, your 
application should unhighlight the menu title by using the HiliteMenu procedure. 


However, if in response to a menu command your application displays a window that 
contains editable text (such as a modal dialog box), you should unhighlight the menu 
title immediately so that the user can access the Edit menu or other appropriate menus. 
In other words, any time the user can use a menu, make sure that the menu title is 

not highlighted. 


When the user chooses a menu command that involves an operation that takes a long 
time, display the animated wristwatch cursor or display a status dialog box to give the 
user feedback that the operation is in progress. 


If you want the users of your application to be able to record their actions (such as menu 
commands, text input, or any sequence of actions) for later playback, your application 
should send itself Apple events whenever a user performs a significant action. To do this 
for menu commands, your application typically sends itself an Apple event to perform 
the action associated with the chosen menu command. For example, when a user 
chooses the New command from the File menu, your application can choose to send 
itself a Create Element event. Your application then creates the new document in 
response to this event. For information on sending Apple events in response to menu 
commands, see Inside Macintosh: Interapplication Communication. 


The next sections show how your application can 
m determine if the user pressed the mouse button while the cursor was in the menu bar 


m adjust its menus—enabling and disabling commands according to the current state of 
the document—before displaying menus or before responding to the user’s choice of a 
keyboard equivalent of a command 


m determine if the user chose the keyboard equivalent of a menu command 
m respond to the user when the user chooses a menu command 


The next sections also show how your application should respond when the user 
chooses an item from the Apple or Help menu. 
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Handling Mouse-Down Events in the Menu Bar 


You can determine when the user has pressed the mouse button while the cursor is in the 
menu bar by examining the event record for a mouse-down event. You can use the 
Window Manager function F indWindow to map the mouse location at the time of the 
mouse-down event to a corresponding area of the screen. If the cursor was in the menu 
bar, your application should call the MenuSelect function, allowing the user to choose 
a menu command. 


Listing 3-17 shows an application-defined procedure, DoEvent, that determines whether 
a mouse-down event occurred and, if so, calls another application-defined procedure to 
handle the mouse-down event. (For a complete discussion of how to handle events, see 
the “Event Manager” chapter in this book.) 


Listing 3-17 Determining whether a mouse-down event occurred 





PROCEDURE DoFvent (event: EventRecord) ; 
BEGIN 
CASE event.what OF 


mouseDown: {handle mouse-down event} 


























DoMouseDown (event) ; 
{handle other events appropriately} 
END; {of CASE} 
END; 











Listing 3-18 shows an application-defined procedure, DoMouseDown, that handles 
mouse-down events. The DoMouseDown procedure determines where the cursor was 
when the mouse button was pressed and then responds appropriately. 


Listing 3-18 Determining when the cursor is in the menu bar 


PROCEDURE DoMouseDown (event: EventRecord) ; 





VAR 
part: Integer; 
thisWindow: WindowPtr; 
BEGIN 
part := FindWindow(event.where, thisWindow) ; 





CASE part OF 
inMenuBar: {mouse down in menu bar, respond appropriately} 
BEGIN 
{adjust marks and enabled state of menu items} 











MyAdjustMenus; 

{let user choose a menu command if desired} 

DoMenuCommand (MenuSelect (event.where) ); 
END; 
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{handle other mouse-down events appropriately} 
END; {of CASE} 
END; 











You can use the FindWindow function to map the mouse location at the time the 
user pressed the mouse button to general areas of the screen. If the mouse location 
is in the menu bar, the FindWindow function returns the constant inMenuBar. In 
Listing 3-18, if the mouse location associated with the mouse-down event is in the 
menu bar, the DoMouseDown procedure first calls another application-defined 
procedure, MyAdjustMenus, to adjust the menus. Listing 3-19 shows the 
MyAdjustMenus procedure. 





The DoMouseDown procedure then calls an application-defined procedure, 
DoMenuCommand. The DoMouseDown procedure passes as a parameter to 
the DoMenuCommand procedure the value returned from the MenuSelect function. 


The MenuSelect function displays menus and handles all user interaction until the user 
releases the mouse button. The MenuSelect function returns a long integer indicating 
whether the user chose a menu command, and if so, it indicates which menu and which 
command the user chose. 


Listing 3-24 on page 3-79 shows the DoMenuCommand procedure. 


Adjusting the Menus of an Application 


Your application should always adjust its menus before calling MenuSelect or 
MenuKey. For example, you should enable and disable any menu items as necessary 
and add checkmarks or dashes to items that are attributes. When you adjust your 
application’s menus, you should enable and disable menu items according to the type 
of window that is in the front. For example, when a document window is the frontmost 
window, you should enable items as appropriate for that document window. When 

a modeless dialog box or modal dialog box is the frontmost window, enable those 
items as appropriate to that particular dialog box. Listing 3-19 shows an application- 
defined routine, MyAdjustMenus, that adjusts the menus of the SurfWriter 
application appropriately. 


The MyAdjustMenus procedure first determines what kind of window is in front 

and then adjusts the application’s menus appropriately. The application-defined 
MyGetWindowType procedure returns a value that indicates whether the window 

is a document window, a dialog window, or a window belonging to a desk accessory. 
It also returns the constant kNil if there isn’t a front window. (See the chapter 
“Window Manager” in this book for a listing of the MyGetWindowType procedure.) 
The MyAdjustMenus procedure calls other application-defined routines to adjust the 
menus as appropriate for the given window type. 
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Listing 3-19 Adjusting an application’s menus 


PROCEDURE MyAdjustMenus; 


VAR 
window: WindowPtr; 
windowType: Integer; 
BEGIN 
window := FrontWindow; 
windowType := MyGetWindowType (window) ; 


CASE windowType OF 


kMyDocWindow: 





BEGIN {document window is in front, adjust items 
appropriately} 
MyAdjustFileMenuForDocWindow; 
MyAdjustEditMenuForDocWindow; 
{adjust other menus as needed} 
END; {of adjusting menus for a document window} 


kMyDialogWindow: 
{adjust menus accordingly for any dialog box} 
MyAdjustMenusForDialogs; 


kDAWindow: {adjust menus accordingly for a DA window} 
MyAdjustMenusForDA; 
kNil: {adjust menus accordingly when there isn't a front 
window} 
MyAdjustMenusNoWindows; 
END; {of CASE} 
DrawMenuBar; 
END; 





Listing 3-20 shows the application-defined procedure 
MyAdjustFileMenuForDocWindow. This procedure enables and disables the File 
menu for the application’s document window, according to the state of the document. 
For example, this application always allows the user to create a new document or open 
a file, so the code enables the New and Open menu items. The code also enables the 
Close, Save As, Page Setup, Print, and Quit menu items. If the user has modified the 
file since last saving it, the code enables the Save command; otherwise, it disables the 
Save command. 


Listing 3-20 Adjusting the File menu for a document window 


PROCEDURE MyAdjustFileMenuForDocWindow; 
VAR 


window: WindowPtr; 
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menu: MenuHandle; 
myData: MyDocRecHnd; 
BEGIN 
window := FrontWindow; 
menu := GetMenuHandle(mFile); {get a handle to the File menu} 
IF menu = NIL THEN {add your own error handling} 





EXIT (MyAdjustFileMenuForDocWindow) ; 
EnableItem(menu, iNew); 





EnableItem(menu, iOpen); 

EnableItem(menu, iClose); 

myData := MyDocRecHnd (GetWRefCon (window) ) ; 

IF myData**.windowDirty THEN 
EnableItem(menu, iSave) 

ELSE 

DisableItem(menu, iSave); 





EnableItem(menu, iSaveAs); 

EnableItem(menu, iPageSetup) ; 

EnableItem(menu, iPrint); 
( 





EnableItem(menu, iQuit); 
END; 





Listing 3-21 shows the application-defined MyAdjustEditMenuForDocWindow 
procedure. 


Listing 3-21 Adjusting the Edit menu for a document window 


PROCEDURE MyAdjustEditMenuForDocWindow; 





VAR 
window: WindowPtr; 
menu: MenuHandle; 
selection, undo: Boolean; 
isSubscriber: Boolean; 
undoText: Str255; 
offset: LongInt; 
BEGIN 
window := FrontWindow; 
menu := GetMenuHandle(mEdit); {get a handle to the Edit menu} 
IF menu = NIL THEN {add your own error handling} 
EXIT (MyAdjustEditMenuForDocWindow) ; 
undo := MyIsLastActionUndoable (undoText) ; 
IF undo THEN {if action can be undone} 
BEGIN 
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SetMenulItemText (menu, iUndo, undoText) ; 





EnableItem(menu, iUndo); 
END 


ELSE {if action can't be undone} 

BEGIN 
SetMenulItemText (menu, iUndo, gCantUndo) ; 
DisableItem(menu, iUndo); 

END; 

selection := MySelection (window) ; 

IF selection THEN 

BEGIN {enable editing items if there's a selection} 
EnableItem(menu, iCut); 
EnableItem(menu, iCopy); 
EnableItem(menu, iCreatePublisher) ; 

END 

ELSE 

BEGIN {disable editing items if there isn't a selection} 
DisableItem(menu, iCut); 
DisableItem(menu, iCopy); 
DisableItem(menu, iCreatePublisher) ; 


END; 
IF GetScrap(NIL, 'TEXT', offset) > 0 THEN 

EnableItem(menu, iPaste) {enable if something to paste} 
ELSE 

DisableItem(menu, iPaste); {disable if nothing to paste} 


EnableItem(menu, iSelectAll); 
EnableItem(menu, iSubscribeTo) ; 
IF MySelectionContainsSubscriberOrPublisher(isSubcriber) THEN 
BEGIN {selection contains a single subscriber or publisher} 
IF isSubscriber THEN {selection contains a subscriber} 
SetMenulItemText (menu, iPubSubOptions, gSubOptText) 
ELSE {selection contains a publisher} 
SetMenulItemText (menu, iPubSubOptions, gPubOptText) ; 
EnableItem(menu, iPubSubOptions) ; 
END 


ELSE {selection contains either no subscribers or publishers } 





{ or contains at least one subscriber and one publisher} 
DisableItem(menu, iPubSubOptions) ; 
IF (gPubCount > 0) OR (gSubCount > 0) THEN 
EnableItem(menu, iShowHideBorders) 
ELSE 
DisableItem(menu, iShowHideBorders) ; 





END; 
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The procedure in Listing 3-21 adjusts the items in the Edit menu as appropriate for a 
document window of the application. The code enables the Undo command if the 
application can undo the last command, enables the Cut and Copy commands if there’s a 
selection that can be cut or copied, enables the Paste command if there’s text data in the 
scrap, and enables the menu items relating to publishers and subscribers appropriately, 
according to whether the current selection contains a publisher or subscriber. The 
application-defined MySelectionContainsSubscriberOrPublisher function 
retums TRUE if the current selection contains a single subscriber or a single publisher and 
returns FALSE otherwise. If the MySelectionContainsSubscriberOrPublisher 
function returns TRUE, the code sets the text for the Publisher Options (or Subscriber 
Options) command and enables the menu item. If the function returns FALSE, the code 
disables the Publisher Options (or Subscriber Options) command. 


Determining if the User Chose a Keyboard Equivalent 


Keyboard equivalents of commands allow the user to invoke a menu command from the 
keyboard. You can determine if the user chose the keyboard equivalent of a menu 
command by examining the event record for a key-down event. If the user pressed the 
Command key in combination with another 1-byte character, you can determine if this 
combination maps to a Command-key equivalent by using the MenuKey function. 


If your application supports keyboard equivalents that use other modifier keys in 
addition to the Command key, your application should examine the modifiers 
field and take any appropriate action; depending on the modifier keys you use, 
your application may or may not be able to use MenuKey to map the key to the 
menu command. 


Listing 3-22 shows an application-defined procedure, DoEvent, that determines whether 


a key-down event occurred and, if so, calls an application-defined routine to handle the 
key-down event. 


Listing 3-22 Determining when a key is pressed 


PROCEDURE DoEvent (event: EventRecord) ; 

BEGIN 
CASE event.what OF 

keyDown, autoKey: {handle keyboard events} 








DoKeyDown (event) ; 
{handle other events appropriately} 
END; {of CASE} 
END; 





If your application determines that the user pressed a key, you need to determine 
whether the user chose the keyboard equivalent of a menu command. You can do this by 
examining the modifiers field of the event record describing the key-down event. If 
the Command key was also pressed, then your application should call the Menukey 
function. The Menukey function scans the current menu list for a menu item that has a 
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matching keyboard equivalent and returns the menu and menu item, if any. Although 
you should not define the same keyboard equivalent for more than one command, the 
MenuKey function scans the menus from right to left, scanning the items from top to 
bottom, and returns the first matching keyboard equivalent that it finds. 


If your application uses other keyboard equivalents in addition to Command-key 
equivalents, you can examine the state of the modifier keys and use the Event Manager 
function KeyTranslate, if necessary, to help map the keyboard equivalent to a 
particular menu item. See the discussion of 'KCHR' resources inInside Macintosh: Text 
for information on how various keyboard combinations map to specific character codes. 


Listing 3-23 shows an application’s DoKeyDown procedure that handles key-down 
events and determines if a keyboard equivalent was pressed. 


Listing 3-23 Checking a key-down event for a keyboard equivalent 


PROCEDURE DoKeyDown (event: EventRecord) ; 




















VAR 
key: Char; 
BEGIN 
key := CHR(BAnd(event.message, charCodeMask) ); 
IF BAnd(event.modifiers, cmdKey) <> 0 THEN 
BEGIN {Command key down} 
IF event.what = keyDown THEN 
BEGIN {first enable/disable/check } 
MyAdjustMenus; { menu items properly} 
DoMenuCommand (MenukKey (key) ); {handle the menu command} 
END; 
END 
ELSE 
MyHandleKeyDown (event) ; 
END; 


Listing 3-23 extracts the pressed key from the message field of the event record and 
then examines the modifiers field to determine if the Command key was also pressed. 
If so, the application first adjusts its menus and then calls an application-defined 
procedure, DoMenuCommand. The DoKeyDown procedure passes as a parameter to 

the DoMenuCommand procedure the value returned from the MenuKey function. 


Listing 3-24 shows the DoMenuCommand procedure. 


Responding When the User Chooses a Menu Item 


Your application can use the MenuSelect function to determine when the user chooses 
a menu command, and your application can use the MenuKey function to determine 
when the user presses the keyboard equivalent for a menu command. Both MenuSelect 
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and MenuKey return a long integer value that indicates which menu and menu item the 
user chose. 


The MenuSelect and MenuKey functions return the menu ID of the menu in the high 
word and the menu item number in the low word of their function result. If the user did 
not choose a menu command or if the user pressed a keyboard combination that does 
not map to any keyboard equivalent in your application’s menus, the functions return 0 
in the high word and the value of the low word is undefined. The MenuSelect function 
also returns 0 in the high word when the user selects an item in the Application or 
Keyboard menu. The MenuSelect function (and MenuKey function, if the command 

has a keyboard equivalent) returns the kHMHelpMenuID constant in the high word and 
the menu item in the low word when the user selects an item that your application 
appended to the Help menu. 


Listing 3-24 shows an application-defined procedure, DoMenuCommand. This procedure 
takes the appropriate action based on which menu command the user chose. 


The DoMenuCommand procedure is called by the application after the application 
determines that either the user pressed the mouse button while the cursor was in the 
menu bar (in which case the application calls MenuSelect to allow the user to choose 
a command) or the user pressed the Command key and another key (in which case the 
application calls the MenuKey function). In either case, the application passes the 
function result returned by MenuSelect orMenuKey as a parameter to the 
DoMenuCommand procedure. 





Listing 3-24 Responding to the user’s choice of a menu command 


PROCEDURE DoMenuCommand (menuResult: LongInt); 





VAR 
menuID, menuItem: Integer; 

BEGIN 
menuID := HiWord(menuResult) ; {get menu ID of menu} 
menulItem := LoWord(menuResult) ; {get menu item number} 
CASE menuID OF 


mApple: 
MyHandleAppleCommand (menulItem) ; 





mFile: 
MyHandleFileCommand (menultem) ; 








MyHandleEditCommand (menultem) ; 
MyHandleFontCommand (menulItem) ; 
MyHandleSizeCommand (menultem) ; 


kHMHelpMenuID: 
MyHandleHelpCommand (menulItem) ; 











mOutline: 
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MyHandleOutlineCommand (menulItem) ; 
mSubMenu: {user chose item from submenu} 
MyHandleSubLabelStyleCommand (menulItem) ; 
END; {end of CASE menuID} 
HiliteMenu(0); {unhighlight what MenuSelect or MenuKey hilited} 
END; 








The DoMenuCommand procedure calls other application-defined routines to perform the 
requested action. After performing the action associated with the chosen menu item, 
your application should use the HiliteMenu procedure to unhighlight the menu title to 
indicate that the requested action is complete. 


Handling the Apple Menu 


When the user chooses an item from the Apple menu, the MenuSelect function returns 
the menu ID of your application’s Apple menu in the high word and returns the chosen 
menu item in the low word of its function result. 


If your application provides an About command as the first menu item in the Apple 
menu and the user chose this item, you should display your application’s About box. 
Otherwise your application should use the GetMenuItemText procedure to get the 
menu item text and then call the OpenDeskAcc function, passing the text of the chosen 
menu item as a parameter. 


Listing 3-25 shows an application-defined procedure, MyHandleAppleCommand, that 
the application calls in response to the user’s choice of an item from the Apple menu. 


Listing 3-25 Responding to the user’s choice of an item from the Apple menu 


PROCEDURE MyHandleAppleCommand (menuItem: Integer); 
VAR 

itemName: Str255; 

daRefNum: Integer; 

















BEGIN 
CASE menuItem OF 
iAbout: {bring up alert for About} 
DisplayMyAboutBox; 
OTHERWISE 
BEGIN {all non-About items in this menu are desktop items, } 
{ for example, DA's, other apps, documents, etc. } 
GetMenulItemText (GetMenuHandle (mApple), menulItem, 
itemName) ; 
daRefNum := OpenDeskAcc (itemName) ; 
END; 
END; {of CASE} 
END; 
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When the user chooses an item other than your application’s About command from 

the Apple menu, your application should call the OpenDeskAcc function. The 
OpenDeskAcc function prepares to open the desktop object chosen by the user; for 
example, if the user chose a document created by the TeachText application, the 
OpenDeskAcc function schedules the TeachText application for execution (or prepares 
to open it if it isn’t already open) and returns to your application. On your application’s 
next call to WaitNextEvent, your application receives a suspend event, and then 

the Process Manager makes TeachText the foreground application and instructs 
TeachText to open the chosen document. 


Handling the Help Menu 


Both the MenuSelect and MenukKey functions return the kHMHe1pMenulID constant 
(—16490) in the high word when the user chooses an appended item from the Help 
menu. The item number of the appended menu item is returned in the low word of the 
function result. 


The DoMenuCommand procedure shown in Listing 3-24 determines which menu 
command was chosen by the user. If the user chose a command from the Help menu, 
the DoMenuCommand procedure calls the application-defined procedure 
MyHandleHelpCommand. Listing 3-26 shows the application-defined procedure 
MyHandleHelpCommand. This procedure illustrates how the SurfWriter application 
responds to the user’s choice of an item from the application’s Help menu. Note that 
you should use the HMGet Hel pMenuHand1le function, not the GetMenuHandle 
function, to get a handle to your application’s Help menu. 


Listing 3-26 Responding to the user’s choice of a command from the Help menu 


PROCEDURE MyHandleHelpCommand (menuItem: Integer) ; 








VAR 
myHelpMenuHdl: MenuHandle; 
origHelpItems, numItems: Integer; 
myErr: OSErr; 

BEGIN 
{get handle to your application's Help menu} 
myErr := HMGetHelpMenuHandle (myHelpMenuHdl1) ; 


IF myErr <> noErr THEN 

EXIT (MyHandleHelpCommand) ; 
{count the number of items in the Help menu} 
numItems := CountMItems (myHelpMenuHd1) ; 
origHelpItems := numItems - kNumMyHelpItems; 
IF menuItem > origHelpItems THEN 





BEGIN {user chose an item added by this application} 

{adjust this application's global variables that hold item } 
{ numbers of the menu items that this application appended} 
gMyHelpIteml := origHelpItems +1; 
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gMyHelpItem2 := origHelpItems +2; 
MyHelp (menulItem) ; 
END; 
END; 





Apple reserves the right to change the number of standard items in the Help menu. To 
determine the number of items in the Help menu, call the CountMItems function. 


Handling a Size Menu 


Your application can provide a Size menu to let the user choose various sizes of a font. 
Your Size menu should also provide the user with a method for specifying a size that 
isn’t currently listed in the menu. For example, you can choose to provide an Other 
command that displays a dialog box allowing the user to choose a different font size. If 
the user chooses a font size not already in the menu, add a checkmark to the Other menu 
command and add the chosen size in parentheses to the text of the Other command. 


Your application should outline font sizes to indicate which sizes are directly provided 
by the current font. For bitmapped fonts, outline only those sizes that actually exist in 
the Fonts folder. For TrueType fonts, outline all sizes that the TrueType font supports. 


Your application should indicate the current font size to the user by placing a checkmark 
next to the text of the menu item that lists the current font size. If the current selection 
contains more than one font size, place a dash next to the name of each font size that the 
selection contains. (“Changing the Mark of Menu Items” on page 3-61 explains how to 
add marks to and remove marks from menu items.) 


Figure 3-35 shows a Size menu as it appears after the user chooses a new font size of 31 
by using the Other command. In Figure 3-35 the sizes 9, 10, 12, 18, 24, and 36 are the 
standard sizes provided by the application. Your application should place a checkmark 
next to the Other command to indicate that the current font size is a size other than a 
standard size. If the selection contains only one nonstandard size, include the size of the 
font in parentheses following the text Other. In Figure 3-35 the current selection contains 
a nonstandard size of 31, so the application places the checkmark next to the Other 
command and includes 31 in parentheses following the Other text. If the selection 
contains multiple nonstandard sizes, include the text Mixed in parentheses following 
the word Other. If the selection contains one or more standard sizes and only one 
nonstandard size, place a dash next to each standard size that the selection contains 

and place a dash next to the Other command with the nonstandard size included in 
paretheses in the text of the Other command. 
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Figure 3-35 A Size menu with user-specified size added 
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When the user chooses the Other command, you should display the current font size in a 
dialog box and allow the user to choose a new size. Figure 3-16 on page 3-28 shows a 
sample dialog box an application might display in response to the user’s choice of the 
Other command. 


You should always specify the text of the Other command in the plain font style (as 
shown in Figure 3-35) and never outlined, regardless of whether the current font is a 
TrueType font that supports that size or a bitmapped font that exists at that size in the 
Fonts folder. 


Listing 3-27 shows an application-defined procedure that handles the user’s choice of an 
item in the Size menu shown in Figure 3-35. 


Listing 3-27 Handling the Size menu 





r 


PROCEDURE MyHandleSizeCommand (menuItem: Integer) ; 
VAR 


numiItems: Integer; 
addiItem: Boolean; 
itemString: Str255; 
itemStyle: Style; 
sizeChosen: LongInt; 
BEGIN 
numItems := CountMItems (GetMenuHandle (mSize) ); 


IF menuItem = numItems THEN 








BEGIN {user chose Other command} 
{display a dialog box to allow the user to choose any } 
{ size. If the user-specified size is not in the menu, } 
{ add a checkmark to the Other command and add the } 

{ new font size to the text of the Other command} 





MyDisplayOtherBox(sizeChosen) ; 
END 


ELSE 
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BEGIN 
IF (menuItem 


(numItems -2)) OR 
(menuItem = (numItems -3)) THEN 





DoMakeLargerOrSmaller(menuItem, sizeChosen) 
ELSE 
BEGIN {user chose size displayed in the menu} 
{remove checkmark or dashes from menu items showing } 
{ previous size} 
MyRemoveMarksFromSizeMenu; 
{add checkmark to menu item of new current size} 
CheckItem(GetMenuHandle (mSize), menuItem, TRUE); 
sizeChosen := MyItemToSize(menulItem) ; 
END; 
END; 
{update the document's state or the user's selection as needed} 
MyResizeSelection(sizeChosen) ; 
END; 

















If the user chooses an item from the Size menu, the MyHandleSizeCommand procedure 
first counts the current number of items in the menu. If the user chooses the last item in 
the menu (the Other command), the procedure displays a dialog box like the one shown 
in Figure 3-16 on page 3-28 to let the user choose a size other than the ones currently 
shown in the menu. The application-defined function MyDisplayOtherBox also adds a 
checkmark to the Other command if the user chose a new size, adds the new size to the 
text of the Other command, and returns the chosen size in the sizeChosen variable. 


If the user chose the Larger or Smaller command from the Size menu, the code calls an 
application-defined routine, DoMakeLargerOrSmaller, to perform the requested 
action. The DoMakeLargerOrSmaller procedure also adds a checkmark and adds the 
new size to the text of the Other command if the new size does not match any size in 
the menu. The procedure returns the chosen size in the sizeChosen variable. 


If the user chose any size currently displayed in the menu, the MyHandleSizeCommand 
procedure adjusts the marking character of the menu items appropriately. The code 
removes the checkmark from the previous menu item and adds a checkmark to the 
menu item representing the new size chosen by the user. The code uses an 
application-defined function, MyItemToSize, to map the item number of the chosen 
menu item to a given size and returns this size in the sizeChosen variable. 


The code then uses the application-defined procedure MyResizeSelection to update 
the document’s state and resize the user’s selection, if any, to the chosen size. 


Accessing Menus From a Dialog Box 


In System 7, the Menu Manager or your application can allow the user to access selected 
menus in the menu bar while interacting with an alert box or a modal dialog box. This 
allows users to make menu selections while your application is displaying an alert box 
or a modal dialog box. For example, a user might want to turn on Balloon Help for 
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assistance in figuring out how to respond to an alert box. Similarly, if the modal dialog 
box contains several editable text fields, the user might find it simpler to copy text 
from one text field and paste it into another. Figure 3-36 shows a modal dialog box 
with an editable text field. Note that only the Edit and Help menus are enabled and all 
other menus are disabled. This gives the user access to editing commands and also to 
Balloon Help. 


Note 

In System 6, user access to menus in the menu bar is prohibited from an 
alert box or a modal dialog box unless your application specifically 
allows it. For example, in System 6, your application must provide a 
filter procedure to replace the standard filter procedure if you want to 
support the keyboard equivalents of the standard Edit menu commands 
in a modal dialog box. In System 7, you can let the Menu Manager 
enable these commands for you. 


Figure 3-36 Menu access from a modal dialog box 
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When your application displays a modeless or movable modal dialog box, your 
application should adjust its menus as appropriate for that dialog box. For example, 
when a movable modal dialog box is the frontmost window, your application should 
enable the Apple menu, enable the Edit menu if your dialog box contains an editable text 
item, enable or disable any other menus as needed, and disable any items it added to the 
Help menu if the user can’t perform those actions while the dialog box is displayed. 


When your application displays an alert box, system software automatically disables all 
of your application’s menus except for the Help menu (in which all items are disabled 
except for the Show Balloons/Hide Balloons command). 


When your application displays a modal dialog box, your application should also enable 
and disable its menus as appropriate. For example, you should enable the Edit menu if 
your dialog box contains an editable text item and disable any items it added to the Help 
menu if the user can’t perform those actions while the dialog box is displayed. If your 
application handles access to the menu bar from a modal dialog box, it should disable 
the Apple menu or the first item in the Apple menu. 


Using the Menu Manager 3-85 


3-86 


CHAPTER 3 


Menu Manager 


If your application does not specifically handle access to the menu bar from an alert box 
or a modal dialog box, in some cases the Menu Manager automatically disables the 
appropriate menus for you, as described in the following paragraphs. 


When your application displays an alert box or a modal dialog box (that is, a window of 
type dBoxProc), the Menu Manager (in conjunction with the Dialog Manager) always 
appropriately adjusts the system-handled menus and performs these actions: 


1. Disables all menu items in the Help menu except the Show Balloons (or Hide 
Balloons) command, which it enables. 


2. Disables all menu items in the Application menu. 


3. Enables the Keyboard menu if it appears in the menu bar, except for the About 
Keyboards command, which it disables. 


In addition, if your application then calls the ModalDialog procedure, the Menu 
Manager (in conjunction with the Dialog Manager) performs two other actions: 


4. Disables all of your application’s menus. 


5. Enables commands with the standard keyboard equivalents Command-x, 
Command-C, and Command-V if the modal dialog box contains a visible and active 
editable text field. The user can then use either the menu commands or their keyboard 
equivalents to cut, copy, and paste text. (The menu item having keyboard equivalent 
Command-X must be one of the first five menu items.) 


When the user dismisses the modal dialog box, the Menu Manager restores all menus to 
the state they were in prior to the appearance of the modal dialog box. 


In some cases actions 4 and 5 do not occur when you call ModalDialog. The enabling 
and disabling described in steps 4 and 5 do not occur if any of these conditions is true: 


m Your application does not have an Apple menu. 


m Your application has an Apple menu, but the menu is disabled when the modal dialog 
box is displayed. 


m Your application has an Apple menu, but the first item in that menu is disabled when 
the dialog box is displayed. 


Note 

If your application already handles access to the menu bar from a 
modal dialog box and you do not want the automatic menu enabling 
and disabling provided by System 7 to occur, you should ensure that 
one or more of those conditions is true when you display a modal 
dialog box. # 


When your application displays alert boxes or modal dialog boxes with no editable 
text items, your application can allow system software to handle menu bar access. In 
all other cases, your application should handle its own menu bar access. 


System software always leaves the Help, Keyboard, and Application menus and their 
commands available when you display movable modal dialog boxes and modeless 
dialog boxes. For these types of dialog boxes, you must disable menus as appropriate 
and handle menu bar access as appropriate given their contents. 
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When your application displays a movable modal dialog box (a window of type 
movableDBoxProc), your application does not need to adjust the system-handled 
menus but should disable all its other menus except the Apple menu and—if your 
movable modal dialog box contains editable text items—the Edit menu. Leave the 
Apple menu enabled so that the user can use it to open other applications, and leave the 
Edit menu enabled so that the user can use the Cut, Copy, and Paste commands within 
the editable text item. (You can also leave your Undo and Clear commands enabled; 
otherwise, disable all other commands in the Edit menu.) 


When your application removes a movable modal dialog box, modeless dialog box, or 
modal dialog box with editable text items, your application must restore to their 
previous states any menus that it disabled prior to displaying the dialog box. See the 
chapter “Dialog Manager” in this book for additional information on dialog boxes. 


Writing Your Own Menu Definition Procedure 


The Menu Manager uses the menu definition procedure and menu bar definition 
function to display and perform basic operations on menus and the menu bar. The 
menu definition procedure performs all the drawing of menu items within a menu 
and performs all the actions that might differ between one type of menu and another. 
The menu bar definition function draws the menu bar and performs most of the 
drawing activities related to the display of menus when the user moves the cursor 
between menus. 


Apple provides a standard menu bar definition function, stored as a resource in the 
System file. The standard menu bar definition procedure is the 'MBDF' resource with 
resource ID 0. When you create your menus and menu bar, by default the Menu 
Manager uses the standard menu bar definition function to manage them. Although the 
Menu Manager lets you provide your own menu bar definition function, Apple 
recommends that you always use the standard menu bar definition function. 





The Menu Manager uses the standard menu bar definition function to 

m= draw the menu bar 

m clear the menu bar 

m determine if the cursor is in the menu bar or any currently displayed menus 

m calculate the left edges of menu titles 

m highlight a menu title 

m= invert the entire menu bar 

m erase the background color of a menu and draw the menu’s structure (shadow) 
m save or restore the bits behind a menu 


Apple provides a standard menu definition procedure, stored as a resource in the System 
file. The standard menu definition procedure is the 'MDEF' resource with resource ID 0. 
The standard menu definition procedure handles three types of menus: pull-down, 
pop-up, and hierarchical; it also implements scrolling in menus. When you define your 
menus, you specify the menu definition procedure that the Menu Manager should use 
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when managing them. You'll usually want to use the standard definition procedure for 
your application. However, if you need a feature not provided by the standard menu 
definition procedure (for example, if you want to include more graphics in your menus), 
you can write your own menu definition procedure. 


The Menu Manager uses the standard menu definition procedure to 
m calculate a menu’s dimensions 


mg draw the menu items in a menu 


highlight and unhighlight menu items as the user moves the cursor between them 
m determine which item the user chose from a menu 


If you provide your own menu definition procedure, it should also perform these tasks. 
Your menu definition procedure should also support scrolling in menus and color in 
menus and provide support for Balloon Help. 


If you provide your own menu definition procedure, store it in a resource of type 

"MDEF'' and include its resource ID in the description of each menu that uses your own 
menu definition procedure. If you create a menu using GetMenu (or Get NewMBar), the 
Menu Manager reads the menu definition procedure into memory and stores a handle to 
it in the menuProc field of the menu’s menu record. 








When your application uses Get Menu (or Get NewMBar) to create a new menu that uses 
your menu definition procedure, the Menu Manager creates a menu record for the menu 
and fills in the menuID, menuProc, enableFlags, and menuData fields according to 
the menu’s resource description. The Menu Manager also reads in the data for each 
menu item and stores it as variable data at the end of the menu record. The menu 
definition procedure is responsible for interpreting the contents of the data. For example, 
the standard menu definition procedure interprets this data as described in “The Menu 
Resource” beginning on page 3-151. After reading in a resource description of a menu, 
the Menu Manager requests the menu definition procedure to calculate the size of 

the menu and to store these values in the menuWidth andmenuHeight fields of the 
menu’s menu record. 


Note that when drawing a menu, the Menu Manager first requests your menu definition 
procedure to calculate the dimensions (the menu rectangle) of the menu. Next the Menu 
Manager requests the menu bar definition function to draw the structure (shadow) of the 
menu and erase the contents of the menu to its background color. Then the Menu 
Manager requests your menu definition procedure to draw the items in the menu. As the 
user moves the cursor into and out of menu items, the Menu Manager requests your 
menu definition procedure to highlight and unhighlight items appropriately. Your menu 
definition procedure should also determine when to add scrolling indicators to a menu 
and scroll the menu appropriately when the cursor is in a scrolling item. Your menu 
definition is responsible for showing and removing any help balloons associated with a 
menu item. 


When the Menu Manager requests your menu definition procedure to perform an action 
on a menu, it provides your procedure with a handle to its menu record. This allows 

your procedure to access the data in the menu record and to use any data in the variable 
data portion of the menu record to appropriately handle the menu items. However, your 
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menu definition procedure should not assume that the A5 register is properly set up, so 
your procedure can’t refer to any of the QuickDraw global variables. 


The Menu Manager passes a value to your menu definition procedure in the message 
parameter that indicates the action your menu definition procedure should perform. The 
Menu Manager always passes a handle to the menu record of the menu that the 
operation should affect in the parameter theMenu. Depending on the requested action, 
the Menu Manager passes additional information in other parameters. 


Listing 3-28 shows how you might declare a menu definition procedure. 


Listing 3-28 A sample menu definition procedure 





PROCEDURE MyMDEF (message: Integer; theMenu: MenuHandle; 
VAR menuRect: Rect; hitPt: Point; 
VAR whichItem: Integer); 





ea 
ic) 
~ 


{any support routines used by the main program of your MD 


{ go here} 


BEGIN 
CASE message OF 





mDrawMsg: 





MyDrawMenu (theMenu, menuRect) ; 
mChooseMsg: 
MyChooseItem(theMenu, menuRect, hitPt, whichItem); 














mSizeMsg: 
MySizeTheMenu (theMenu) ; 
mPopUpMsg: 
MyCalcMenuRectForOpenPopUpBox(theMenu, hitPt, menuRect); 
END; 
END; 


The next sections describe in more detail how your menu definition procedure should 
respond when it receives the mDrawMsg, mChooseMsg, ormSizeMsg constant in the 
message parameter. For a complete description of the menu definition procedure and 
the parameters passed to your procedure by the Menu Manager, see “The Menu 
Definition Procedure” beginning on page 3-148. 


Calculating the Dimensions of a Menu 


Whenever the Menu Manager creates a menu or needs to calculate the size of a menu 
that is managed by your menu definition procedure, the Menu Manager calls your 
procedure and specifies the mSizeMsg constant in the message parameter, requesting 
that your procedure calculate the size of the menu. 
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Listing 3-29 on page 3-90 shows an application-defined support routine, 
MySizeTheMenu, used by the application’s menu definition procedure. After 
calculating the height and width of the menu’s rectangle, the menu definition 
procedure stores the values in the menuWidth andmenuHeight fields of the 
menu’s menu record. 


Listing 3-29 Calculating the size of a menu 





PROCEDURE MySizeTheMenu (theMenu: MenuHandle) ; 


VAR 
itemDataPtr: Ptr; 
numitems: Integer; 
BEGIN 





HLock (Handle (theMenu) ) ; 
WITH theMenu*%* DO 
BEGIN {menuData points to title of menu and additional item data} 
itemDataPtr := @menuData; 
{skip past the menu title} 
itemDataPtr := POINTER(ORD4 (itemDataPtr)+ itemDataPtr%’® +1); 
END; 
numIitems := CountMItems (theMenu) ; 
{calculate the height of the menu--each item's height can vary } 
{ according to whether the item has an icon or a script code defined. } 
{ The height of the menu should not exceed the height of the } 
{ screen minus the menu bar height. } 





{ Store the height in the menu's menu record} 
theMenu**.menuHeight := MyCalcMenuHeight (itemDataPtr, numItems) ; 


{calculate the width of the menu (the width of the longest item): } 





for each item calculate the width as } 
width = iconWidth + markWidth + textWidth + subMenuWidth } 
+ cmdKeyComboWidth } 
If an item doesn't have a characteristic, use 0 as the width of } 
that characteristic. } 
To calculate the width of item's text, must consider script code and } 
width of the font. } 
The width of the menu should not exceed the right or left } 
boundaries of the screen. } 


Ee en ce ee 


Store the width in the menu's menu record} 
theMenu’*.menuWidth := MyCalcMenuWidth(itemDataPtr, numItems) ; 
HUnLock (Handle (theMenu) ) ; 

END; 
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Drawing Menu Items in a Menu 


Wherever the user presses the mouse button while the cursor is in the menu title of a 
menu managed by your menu definition procedure, the Menu Manager calls the menu 
bar definition function to highlight the menu title, draw the structure of the menu, and 
erase the contents of the menu to its background color. The Menu Manager then calls 
your menu definition procedure and specifies the mDrawMsg constant in the message 
parameter, requesting that your procedure draw the menu items. When your menu 
definition procedure receives this constant, it should draw the menu items of the menu 
specified by the parameter theMenu inside the rectangle specified by the menuRect 
parameter. The Menu Manager sets the current graphics port to the Window Manager 
port before calling your menu definition procedure. Your menu definition procedure can 
determine how to draw the menu items by examining the data in the menu record. 


If your menu definition procedure supports color menus, your procedure should 

check the application’s menu color information table for the colors to use to draw 

each item. If the application’s menu color information table contains a color entry for 

an item, draw the item using that color. If the table does not contain an item entry for 

a particular item, use the default item color defined in the menu title entry. If a menu title 
entry doesn’t exist, use the default item color defined in the menu bar entry. If the menu 
bar entry doesn’t exist, draw the item using black on white. 


If your menu definition procedure supports scrolling menus, it should insert scrolling 
indicators if necessary when drawing the menu items. 


Listing 3-30 shows an application-defined support routine, MyDrawMenu, used by the 
application’s menu definition procedure. The MyDrawMenu procedure draws each item 
in the menu, according to the item’s defined characteristics. Disabled items should be 
drawn using the colors returned by the Get Gray function. Pass the RGB color of the 
item’s background in the bkgnd parameter to the Get Gray function; pass the RGB color 
of the item’s enabled text in the fgnd parameter. The Get Gray function returns TRUE if 
there’s an available color between the two specified colors and returns in the fgnd 
parameter the color in which you should draw the item. 





Listing 3-30 Drawing menu items 








PROCEDURE MyDrawMenu (theMenu: MenuHandle; menuRect: Rect); 
VAR 

numiItems: Integer; 

itemRect: Rect; 

item: Integer; 


currentOffset: LongInt; 


nextOffset: LongInt; 
BEGIN 
numItems := CountMItems (theMenu) ; 
currentOffset := 0; 
nextOffset := 0; 
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FOR item := 1 TO numItems DO 
BEGIN 
{calculate the enclosing rectangle for this item} 





itemRect := MyCalcItemRect (item, menuRect, currentOffset, nextOffset); 
{draw the item--index into the item-specific data from the menu record } 
to get the characteristics of this menu item and draw the item } 
according to its defined characteristics. For example, draw the item's } 
text in its defined style & font of its defined script, draw any icon, } 
mark, submenu indication, or keyboard equivalent, and draw each } 
characteristic of the item according to its color entry in the menu's } 
menu color information table. } 
Draw disabled items in gray--use the GetGray function to return the } 


appropriate color. Also draw dividers using the gray color } 


Fo ee ee ee 


returned by GetGray} 





MyDrawTheItem(item, itemRect, menuRect, currentOffset); 
END; 
{if your menu supports scrolling, insert scrolling indicators if needed} 
MyInsertScrollingArrows (menuRect) ; 


, 


Determining Whether the Cursor Is in an Enabled Menu Item 


Whenever the user drags the cursor into or out of a menu item of a displayed menu 
managed by your menu definition procedure, the Menu Manager calls your procedure 
and specifies the mchooseMsg constant in the message parameter, requesting that 
your procedure determine whether the cursor is in a menu item and that your procedure 
highlight or unhighlight the menu item as appropriate. When your menu definition 
procedure receives this constant, it should use the menu rectangle specified in the 
menuRect parameter, the mouse location specified in the hitPt parameter, and the 
item number specified in the wnichItem parameter to determine the proper action 

to take. 


To see whether the user chose an enabled item, your menu definition procedure should 
determine whether the specified mouse location is inside the rectangle specified by the 
menuRect parameter, and, if so, it should check whether the menu is enabled. If the 
menu is enabled, your menu definition procedure should determine whether the mouse 
location specified in the hitPt parameter is in an enabled menu item. 


If the mouse location is in an enabled menu item, your menu definition procedure 
should unhighlight the item specified by the whichItem parameter, highlight the new 
item, and return the new item number in whichItem. 


If the mouse location isn’t in an enabled menu item, your menu definition procedure 
should unhighlight the item specified by the wnichItem parameter and return 0 in 
the whichItem parameter. 
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When your menu definition procedure draws a menu item in its highlighted state in a 
color menu, it should reverse the background color and the item color and then draw the 
menu item. When your menu definition procedure needs to return a menu item to its 
normal (unhighlighted) state, it should reset the background color and item color of that 
menu item and draw the menu item. 


If your menu definition procedure supports scrolling menus, it should scroll the menu 
when the user moves the cursor into the area of the indicator, or when the cursor is 
directly above or below the menu. If the user can scroll the menu up (by dragging the 
cursor past the last item to view more items), place a downward-pointing triangular 
indicator in place of the last item in the menu. If the user can scroll the menu down 
(by dragging the cursor past the first item to view the items originally at the top of 

the menu), place an upward-pointing triangular indicator in place of the first item 

in the menu. 


For all menus, your menu definition procedure should set the global variable 
MenuDisable appropriately each time a new item is highlighted. Set MenuDisableto 
the menu ID and item number of the last menu item chosen, whether or not it’s disabled. 
The MenuChoice function uses the value in MenuDisab1le to determine if a chosen 
menu item is disabled. 


Listing 3-31 shows an application-defined support routine, MyChooseItem, used by the 
application’s menu definition procedure. This routine determines which item, if any, the 
point specified by the hitPt parameter is in. If the item is in an enabled menu item that 
is different from the previous item, the MyChooseItem procedure unhighlights the old 
item and highlights the new item. However, the MyChooseItem procedure does not 
highlight the new item if the item is in a divider or disabled item. 


The procedure also removes any help balloons as appropriate and, if Balloon Help is 
turned on, displays any help balloon of the new item (for any item other than a divider 
or scrolling indicator). The MyChooseItem procedure returns the item number of the 
new item in the whichItem parameter or returns 0 if no item is chosen. Although not 
shown in the listing, if the item is a disabled item, the procedure returns 0 in the 
whichItem parameter and sets the MenuDisab1e global variable to the menu ID and 
item number of the disabled item. 


Listing 3-31 Choosing menu items 








PROCEDURE MyChooseItem (theMenu: MenuHandle; menuRect: Rect; hitPt: Point; 
VAR whichItem: Integer); 
VAR 
oldWhichItem: Integer; 
MenuChoicePtr: “LongInt; 
numItems, item, max: Integer; 
itemChosen: Integer; 
inScroll: Integer; 
currentOffset: LongInt; 
nextOffset: LongInt; 
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BEGIN 
oldWhichItem := whichItem; 
whichItem := 0; 
itemChosen := 0; 
MenuChoicePtr := POINTER(kLowMemMenuDisable) ; 
numitems := CountMItems (theMenu) ; 


{find out whether the hitPt is in an item's rectangle, and if so, } 

{ determine which item} 

item := 1; 

max := numItems + 1; 

currentOffset := 0; 

nextOffset := 0; 

REPEAT 
itemRect := MyCalcItemRect (item, menuRect, currentOffset, nextOffset); 
IF PtInRect (hitPt, itemRect) THEN {hitPt is in this item} 


itemChosen := item; 





item := item + 1; 
UNTIL (item = MAX) OR (itemChosen <> 0); 
IF itemChosen = 0 THEN 
BEGIN {the mouse isn't in any item of this menu;unhighlight previous item} 
MyNotInMenu(menuRect, oldWhichItem) ; 
END 
ELSE 
BEGIN {the mouse is in this menu item. } 
{ First see if a previous item was highlighted} 
IF ((oldWhichItem <> 0) AND (oldWhichItem <> itemChosen)) THEN 


BEGIN 
{a previous item was highlighted--unhighlight it} 
itemRect := MyCalcOldItemRect (oldWhichItem, menuRect) ; 


IF HMGetBalloons THEN {if Balloon Help is on then } 
HMRemoveBalloon; { remove any balloon that might be showing} 
MyHighlightItem(itemRect, oldWhichItem, FALSE) ; 
END; 
IF HMGetBalloons and MyIsItemDivider(itemChosen) THEN 
{Balloon Help is on and item is divider} 
HMRemoveBalloon; {remove any balloon that might be showing} 
IF MyIsItemEnabled(itemChosen) THEN 
BEGIN 
{the item is enabled, so highlight the item the cursor is in} 








itemRect := MyCalcNewItemRect (itemChosen, menuRect, currentOffset); 
{the highlighting routine must also support scrolling correctly } 

{ (if the cursor is in a scrolling item, don't highlight the item) } 
inScroll := MyIsScrolliItem(itemChosen) ; 
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MyHighlightItem(itemRect, itemChosen, inScroll); 
IF HMGetBalloons AND inScroll THEN 
HMRemoveBalloon {remove any balloon that might be showing} 
ELSE 
BEGIN {display help balloon for this item, if any} 
IF HMGetBalloons THEN 








BEGIN 
IF StillDown THEN {mouse button is still down in this item} 





{this routine sets up the needed parameters and then } 
{ calls HMShowMenuBalloon} 
MyShowMenuBalloon(itemChosen, itemRect); 

















Menu Manager Reference 


This section describes the data structures and routines of the Menu Manager. It also 
describes various resources, including the resources you can use to create your menus 
and menu bar, the 'MBAR' and 'MENU' resources. 





Data Structures 


This section describes the menu record, menu list, and menu color information table. The 
Menu Manager maintains information about the menus in your application in menu 
records. The Menu Manager maintains information about all the menus in a menu bar in 
a data structure called the menu list. 


The Menu Manager stores color information about your application’s menus in a menu 
color information table. You can add entries to your application’s menu color 
information table if you want to use colors other than the default colors for your menu 
bar or menus. You can add entries to this table by using the SetMCEnt ries procedure 
or by providing 'mctb' resources. 





The Menu Record 


A menu record contains information about a single menu. Your application should never 
manipulate or access the fields of a menu record; instead your application should use 
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Menu Manager routines to create and manage the menus in your application. To refer to 
a menu, use a handle to the menu’s menu record. 


The MenuInfo data type defines the menu record. The MenuHand1e data type is a 
handle to a menu record. 


TYPE MenuPtr “MenulInfo; {pointer to a menu record} 


MenuHandle = *MenuPtr; {handle to a menu record} 
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Here is the structure of a menu record: 








TYPE MenulInfo = {menu record} 
RECORD 
menulID: Integer; {number that identifies the menu} 
menuWidth: Integer; {width (in pixels) of the menu} 
menuHeight: Integer; {height (in pixels) of the menu} 
menuProc: Handle; {menu definition procedure} 
enableFlags: LongInt; {indicates whether menu and } 


{ menu items are enabled} 





menuData: Str255; {title of menu} 
{itemDefinitions} {variable-length data that } 
{ defines the menu items} 
END; 


Field descriptions 

menuID A number that identifies the menu. Each menu in your application 
must have a unique menu ID. Your application specifies the menu 
ID when you create the menu. Thereafter you can use the menu ID 
and the GetMenuHand1le function to get a handle to the menu’s 
menu record. 


When you define hierarchical menus, you must use a number from 
1 through 235 for the menu ID of a submenu of an application; use a 
number from 236 through 255 for the submenu of a desk accessory. 


menuWidth The horizontal dimensions of the menu, in pixels. 
menuHeight The vertical dimensions of the menu, in pixels. 
menuProc A handle to the menu definition procedure of the menu. The Menu 


Manager uses this menu definition procedure to draw the menu. 


enableFlags A value that represents the enabled state of the menu title and 
the first 31 items in the menu. All menu items greater than 31 
are enabled by default and can be disabled only by disabling the 
entire menu. 


menuData A string that defines the title of the menu. Although the menuData 
field is defined by the data type Str255 in the MenuInfo data 
structure, the Menu Manager allocates only the storage necessary 
for the title: the number of characters in the title of the string plus 1. 

itemDefinitions 
Variable-length data that defines the characteristics of each menu 
item in the menu. If the menu uses the standard menu definition 
procedure, this data can be conceptually defined in this manner: 


itemData: ARRAY[1..X] OF 
itemString: String; {text of menu item} 
itemIcon: Byte; {icon number minus 256} 
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itemCmd: Char; {keyboard equivalent or } 
value ($1B) indicating } 
item has a submenu, or } 
($1C) if item has } 

a script code, or } 
($1D) if item's 'ICON' } 
should be reduced, or } 
(S1E) if item has an } 

{ 'SICN' icon} 


AAA DHHS 





itemMark: Char; {marking character or } 
{ menu ID of submenu} 
itemStyle: Style; {style of menu text} 
endMarker: Byte; {contains 0 if no } 


{ more menu items} 
The menu definition procedure maintains the information about the 
menu items. You typically define your menu items in 'MENU' 
resources, and the Menu Manager stores information describing 
your items in the menu’s menu record. 


Your application should not directly change the values of any fields in a menu record. 
Use Menu Manager routines to change the characteristics of menu items or to make 
other changes to a menu. 


The Menu List 


The menu list contains information about the menus in a menu bar, about submenus, 
and about pop-up menus. A menu list contains handles to the menu records of zero, 
one, or more menus and contains other information that the Menu Manager uses to 
manage menus. 


The InitMenus procedure creates the current menu list of an application. The current 
menu list contains handles to the menu records of all menus currently in the menu bar 
and handles to the menu records of any submenus or pop-up menus inserted into the 
menu list by your application. The menu bar shows the titles, in order, of all menus 
(other than submenus or pop-up menus) in the menu list. 


The initial menu list created by InitMenus does not contain handles to any menus. The 
Menu Manager dynamically allocates storage in a menu list as menus are added to and 
deleted from the menu list. 


Your application should not directly change or access the information in a menu list. You 
should use Menu Manager routines to create a menu list and to add menus to or remove 
menus from the current menu list. 





You typically define your application’s menu bar in an 'MBAR" resource and create a 
menu list using the Get NewMBar function. The Get NewMBar function returns a handle 
to a menu list. You can set the current menu list to the menu list returned by 
GetNewMBar using the SetMenuBar procedure. 
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The structure of the menu list is private to the Menu Manager. For conceptual purposes, 
however, its general structure is defined here. 


DynamicMenuList = 
RECORD 
lastMenu: Integer; {offset to last pull-down menu} 
lastRight: Integer; {pixel location of right edge } 
{ of rightmost menu in menu bar} 
mbResID: Integer; {upper 13 bits are the resource ID of menu } 
{ bar defn function, low 3 bits the variant} 
menu: ARRAY[1..X] {variable array with one record for } 
OF MenuRec; { each menu} 
lastHMenu: Integer; {offset to last submenu or pop-up menu} 
menuTitleSave: {handle to bits behind inverted menu title} 
pixMapHandle; 
hMenu: ARRAY[1..Y] {variable array with one record for } 


END; 


OF HMenuRec;{ each submenu or pop-up menu} 


The Menu Manager dynamically allocates the records that contain handles to the menu 
records of menus in the menu bar, submenus, and pop-up menus. These records can be 
defined conceptually as the MenuRec and HMenuRec data types. The Menu Manager 
uses a data structure similar to that of the MenuRec data type to store information about 
pull-down menus in the menu list. 


TYPE MenuRec = 


RECORD 
menuOH: MenuHandle; {handle to menu's menu record} 
menuLeft: Integer; {pixel location of left edge } 
{ of this menu} 
END; 


The Menu Manager stores information about submenus and pop-up menus at the end of 
a menu list in a data structure similar to that of the HMenuRec data type. 


TYPE HMenuRec = 


RECORD 
menuHOH: MenuHandle; {handle to menu's menu record} 
reserved: Integer; {reserved} 

END; 





The Menu Color Information Table Record 
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Your application’s menu color information table defines the standard color for the 
menu bar, titles of menus, text and characteristics of menu items, and background color 
of a displayed menu. If you do not add any entries to this table, the Menu Manager 
draws your menus using the default colors, black on white. You can add colors to your 
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menus by adding entries to your application’s menu color information table by using 
Menu Manager routines or by defining these entries in an 'mctb' resource. Note that 
the menu color information table uses a format that is different from the standard color 
table format. 


The Menu Manager maintains information about an application’s menu color 


information table as an array of menu color entry records. 


TYPE MCTable = ARRAY[0..0] OF MCEntry; {menu color table} 
MCTablePtr = *“MCTable; {pointer to a menu color table} 
MCTableHandle = *“MCTablePtr; {handle to a menu color table} 


A menu color entry is defined by the MCEnt ry data type. 


TYPE MCEntry = {menu color entry} 
RECORD 
mctID: Integer; {menu ID or 0 for menu bar} 
mctItem: Integer; {menu item number or 0O for } 


{ menu title} 








mctRGB1: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctRGB2: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctRGB3: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctRGB4: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctreserved: Integer; {reserved} 
END; 
MCEntryPtr = *MCEntry; {pointer to a menu color entry} 


The first two fields of a menu color entry record, mct ID andmct Item, define whether 
the entry is a menu bar entry, a menu title entry, or a menu item entry. The following 
four fields specify color information for whatever type of entry the mct ID andmct Item 
fields describe. The value of the mct ID field in the last entry in a menu color information 
table is —99, and the rest of the fields of the last entry are reserved. The Menu Manager 
automatically creates the last entry in a menu color information table; your application 
should not use the value —99 as the menu ID of a menu if you wish to add a menu color 
entry for it. 


The Menu Manager creates your application’s menu color information table the first 
time your application calls InitMenus or InitProcMenu. It creates the menu color 
information table as initially empty except for the last entry, which indicates the end 
of the table. 
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Table 3-7 shows how the Menu Manager interprets the mct ID andmct Item fields for 
each type of menu color entry in a menu color information table. 


Table 3-7 Color information for menu entries 
ID Item RGB1 RGB2 RGB3 RGB4 
0 0 Default Default back- Default Default bar 
menu title ground color item color color 
color of menus 
N<>0 0 Menu title Bar color Default Background 
color item color color of 
menu 
N<>0 M<>0 Mark color Item text Keyboard Background 
color equivalent color of 
color menu 
-99 Reserved Reserved Reserved Reserved Reserved 


A menu bar entry is defined by a menu color entry record that contains 0 in both the 
mct ID andmct Item fields. You can define only one menu bar entry in a menu color 
information table. If you don’t provide a menu bar entry for your application’s menu 
color information table, the Menu Manager uses the standard menu bar colors (black text 
ona white background), and it uses the standard colors for the other menu elements. 
You can provide a menu bar entry to specify default colors for the menu title, the 
background of a displayed menu, the items in a menu, and the menu bar. The color 
information fields for a menu bar entry are interpreted as follows: 





m™ mctRGB1 specifies the default color for menu titles. If a menu doesn’t have a menu 
title entry, the Menu Manager uses the value in this field as the color of the menu title. 


™ mctRGB2 specifies the default color for the background of a displayed menu. If a 
menu doesn’t have a menu title entry, the Menu Manager uses the value in this field 
as the color of the menu’s background when it is displayed. 


m™ mctRGB3 specifies the default color for the items in a displayed menu. If a menu item 
doesn’t have a menu item entry or a default color defined in a menu title entry, the 
Menu Manager uses the value in this field as the color of the menu item. 


m™ mctRGB4 specifies the default color for the menu bar. If a menu doesn’t have a menu 
bar entry (and doesn’t have any menu title entries), the Menu Manager uses the 
standard colors for the menu bar. 


A menu title entry is defined by a menu color entry record that contains a menu ID in 
the mct ID field and 0 in the mct Item field. You can define only one menu title entry for 
each menu. If you don’t provide a menu title entry for a menu in your application’s 
menu color information table, the Menu Manager uses the colors defined by the menu 
bar entry. If a menu bar entry doesn’t exist, the Menu Manager uses the standard colors 
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(black on white). You can provide a menu title entry to specify a color for the title and 
background of a specific menu and a default color for its items. The color information 
fields for a menu title entry are interpreted as follows: 


m™ mctRGB1 specifies the color for the menu title of the specified menu. If a menu 
doesn’t have a menu title entry, the Menu Manager uses the default value defined 
in the menu bar entry. 


m™ mctRGB2 specifies the default color for the menu bar. If a menu color information 
table doesn’t have a menu bar entry, the Menu Manager uses the value in this field as 
the color of the menu bar. If a menu bar entry already exists, the Menu Manager 
replaces the value in the mct RGB2 field of the menu title entry with the value defined 
in the mct RGB4 field of the menu bar entry. 





m™ mctRGB3 specifies the default color for the items in the menu. If a menu item doesn’t 
have a menu item entry or a default color defined in a menu bar entry, the Menu 
Manager uses the value in this field as the color of the menu item. 


m™ mctRGB4 specifies the color for the background of the menu. 


A menu item entry is defined by a menu color entry record that contains a menu ID in 
the mct ID field and an item number in themct Item field. You can define only one 
menu item entry for each menu item. If you don’t provide a menu item entry for an item 
in your application’s menu color information table, the Menu Manager uses the colors 
defined by the menu title entry (or by the menu bar entry if the menu containing the 
item doesn’t have a menu title entry). If neither a menu title entry nor a menu bar entry 
exists, the Menu Manager draws the mark, text, and keyboard equivalent in black. You 
can provide a menu item entry to specify a color for the mark, text, and keyboard 
equivalent of a specific menu item. The color information fields for a menu item entry 
are interpreted as follows: 





m™ mctRGB1 specifies the color for the mark of the menu item. If a menu item doesn’t 
have a menu item entry, the Menu Manager uses the default value defined in the 
menu title entry or the menu bar entry. 


m™ mctRGB2 specifies the color for the text of the menu item. If a menu item doesn’t have 
a menu item entry, the Menu Manager uses the default value defined in the menu title 
entry or the menu bar entry. The Menu Manager also draws a black-and-white icon of 
a menu item using the same color as defined by the mct RGB2 field. (Use a 'cicn' 
resource to provide a menu item with a color icon.) 


m™ mctRGB3 specifies the color for the keyboard equivalent of the menu item. If a menu 
item doesn’t have a menu item entry, the Menu Manager uses the default value 
defined in the menu title entry or the menu bar entry. 





m™ mctRGB4 specifies the color for the background of the menu. If the menu color 
information table doesn’t have a menu title entry for the menu this item is in, or 
doesn’t have a menu bar entry, the Menu Manager uses the value in this field as the 
background color of the menu. If a menu title entry already exists, the Menu Manager 
replaces the value in the mct RGB4 field of the menu item entry with the value defined 
in the mct RGB4 field of the menu title entry (or with the mct RGB2 field of the menu 
bar entry). 
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You can use the GetMCInfo function to get a copy of your application’s menu color 
information table and the SetMCEntries procedure to set entries of your application’s 
menu color information table, or you can provide 'mctb' resources that define the color 
entries for your menus. 





The GetMenu, GetNewMBar, and ClearMenuBar routines can also modify the entries in 
the menu color information table. The GetMenu function looks for an 'mctb' resource 
with a resource ID equal to the value in the menuID parameter. If it finds one, it adds the 
entries to the application’s menu color information table. 


The GetNewMBar function builds a new menu color information table when it creates 
the new menu list. If you want to save the current menu color information table, call 
GetMCInfo before calling Get NewMBar. 





The ClearMenuBar procedure reinitializes both the current menu list and the menu 
color information table. 
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The Menu Manager includes routines for creating menus, changing the characteristics of 
menu items, and handling user choice of menu commands. The Menu Manager also 
provides routines for adding items to and deleting items from menus, counting the 
number of items in a menu, getting a handle to a menu’s menu record, disposing of 
menus, calculating the dimensions of a menu, highlighting the menu bar, and managing 
entries in your application’s menu color information table. 


Some Menu Manager routines can be accessed using more than one spelling of the 
routine’s name, depending on the interface files supported by your development 
environment. For example, GetMenuHand1e is also available as GetMHandle. 
Table 3-8 provides a mapping between the previous name of a routine and its new 
equivalent name. 





Table 3-8 Mapping between new and previous names of Menu Manager routines 
New name Previous name 

AppendResMenu AddResMenu 

DeleteMCEntries DelMCEntries 

DeleteMenuItem DelMenuItem 

DisposeMCInfo DispMCInfo 

GetMenuHandle GetMHandle 

GetMenuItemText GetItem 

InsertMenuItem InsMenuItem 

SetMenulItemText SetItem 
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Initializing the Menu Manager 


InitMenus 


DESCRIPTION 


You can use the InitMenus procedure to initialize the Menu Manager. 


You can use the InitProcMenu procedure to set the current menu list so that it uses a 
custom menu bar definition function if necessary. 


The InitMenus procedure allocates space for your application’s current menu list in 
your application’s heap. Your application needs to call InitMenus only once to 
initialize the Menu Manager and the current menu list for your application. 





PROCEDURE InitMenus; 











The InitMenus procedure creates the current menu list with no menus, submenus, or 
pop-up menus. InitMenus also creates your application’s menu color information 
table. After allocating the menu color information table, InitMenus looks for an 
"mctb' resource with resource ID 0. You can provide an 'mctb' resource with a 
resource ID of 0 as one of your application’s resources if you want to use colors other 
than the default colors for your application’s menu bar and menus. If InitMenus finds 
and successfully loads an 'mctb' resource, it adds the information contained in that 
resource to the menu color information table (using SetMCEnt ries). 





The InitMenus procedure also draws an empty menu bar. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


Your application must initalize QuickDraw, the Font Manager, and the Window Manager 
(using the InitGraf, InitFonts, and InitWindows procedures) before initializing 
the Menu Manager. 


To set up the menus for your application’s menu bar, use GetNewMBar and 
SetMenuBar, described on page 3-111 and page 3-112, respectively. You can also add 
menus to the current menu list using the InsertMenu procedure, described on 

page 3-108. 





To remove all menus from the current menu list, use the ClearMenuBar procedure, 
described on page 3-110. 


If your application uses its own menu bar definition function, use the InitProcMenu 
procedure to set the mbResID field of the current menu list to the resource ID of your 
custom 'MBDF' resource. 
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See “The Menu Color Information Table Resource” on page 3-155 for a description of the 
'mctb" resource. 


See the chapter “Window Manager” in this book for a description of the InitWindows 
procedure. See Inside Macintosh: Imaging and Inside Macintosh: Text for descriptions of the 
InitGraf and InitFonts procedures. 


InitProcMenu 


DESCRIPTION 


Apple recommends that you use the standard menu bar definition function. However, if 
your application provides its own menu bar definition function, use the InitProcMenu 
procedure to set the mbResID field of the current menu list to the resource ID of your 
custom 'MBDF'' resource. 


PROCEDURE InitProcMenu (resID: Integer) ; 


resID The resource ID of your application’s menu bar definition function in the 
upper 13 bits of this parameter; the variant in the lower 3 bits. You must 
use a resource ID greater than $100. 
For resources of type 'MBDF', Apple reserves resource IDs $000 through 
$100 for its own use. 


The InitProcMenu procedure creates the current menu list if it hasn’t already been 
created by a previous call to InitMenus. The InitProcMenu procedure stores the 
resource ID that you specify in the mbResID field of the current menu list. The Menu 
Manager uses the menu bar definition function referred to in this field to draw the menu 
bar and to perform basic operations on menus. 


SPECIAL CONSIDERATIONS 


SEE ALSO 
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The resource ID of your application’s menu bar definition function is maintained in the 
current menu list until your application next calls InitMenus; InitMenus initializes 
the mbResID field with the resource ID of the standard menu bar definition function. 
This can affect applications such as development environments that control other 
applications that may call InitMenus. 


See the description of the InitMenus procedure on page 3-103; you should use 
InitMenus if your application uses the standard menu bar definition function. 
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Creating Menus 


NewMenu 





You can use the NewMenu or GetMenu function to create a pull-down menu, although 
you usually create all the menus in your menu bar at once by providing an 'MBAR' 
resource and using the Get NewMBar function. See “Getting and Setting the Menu Bar” 
on page 3-112 for information on creating a menu bar. You typically use the NewMenu or 
GetMenu function to create submenus or pop-up menus. 








The NewMenu function creates a menu with the specified title, assigns it the specified 
menu ID, and creates a menu record for the menu. Use AppendMenu, 
InsertMenulItem, AppendResMenu, or InsertResMenu to add items to menus you 
create with NewMenu. 





The GetMenu function creates a menu with the title, items, and characteristics defined in 
a specified 'MENU' resource. 





Both NewMenu and GetMenu allocate space in your application’s heap for the menu 
record and return a handle to the menu’s newly created menu record. 


To add menus created by NewMenu or Get Menu to the current menu list, use the 
InsertMenu procedure. To update the menu bar with any new menu titles, use 
DrawMenuBar. 


You can use the NewMenu function to create an empty menu with a specified title and 
menu ID. In most cases you should store information about your menus (such as their 
titles, items, and characteristics) in resources; use the GetMenu or Get NewMBar function 
to create menus from resource definitions. 








FUNCTION NewMenu (menuID: Integer; menuTitle: Str255): MenuHandle; 


menuID The menu ID of the menu. (Note that this is not the resource ID of a 
'MENU' resource.) The menu ID is a number that identifies the menu. Use 
positive menu IDs for menus belonging to your application. Use negative 
menu IDs for desk accessories (except for submenus of a desk accessory). 
Submenus must have menu IDs from 1 through 255. For submenus of an 
application, use menu IDs from 1 through 235; for submenus of a desk 
accessory, use menu IDs from 236 through 255. Apple reserves the menu 
ID of 0. 


menuTitle The title of the new menu. Note that in most cases you should store 
the titles of menus in resources, so that your menu titles can be more 
easily localized. 
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The NewMenu function creates a menu with the specified title, assigns it the specified 
menu ID, creates a menu record for the menu, and returns a handle to the menu record. 
It sets up the menu record to use the standard menu definition procedure (and it reads 
the standard menu definition procedure into memory if it isn’t already there). The 
NewMenu function does not insert the newly created menu into the current menu list. 


After creating a menu with NewMenu, use AppendMenu, InsertMenulItem, 
AppendResMenu, or InsertResMenu to add menu items to the menu. To add a menu 
created by NewMenu to the current menu list, use the InsertMenu procedure. To update 
the menu bar with any new menu titles, use the DrawMenuBar procedure. 





SPECIAL CONSIDERATIONS 


SEE ALSO 


GetMenu 
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To release the memory associated with a menu that you created using NewMenu, first 
call DeleteMenu to remove the menu from the current menu list and to remove any 
entries for this menu in your application’s menu color information table; then call 
DisposeMenu to dispose of the menu’s menu record. After disposing of a menu, use 
DrawMenuBar to update the menu bar. 


If the NewMenu function is unable to create the menu record, it returns NIL as its 
function result. 


For information on how to add items to a menu, see the description of AppendMenu on 
page 3-124, InsertMenuItem on page 3-126, AppendResMenu on page 3-128, and 
InsertResMenu on page 3-129. For information on InsertMenu, see page 3-108. To 
dispose of a menu, see the description of Delet eMenu on page 3-109 and DisposeMenu 
on page 3-140. 


Use the GetMenu function to create a menu with the title, items, and other characteristics 
defined in a 'MENU' resource with the specified resource ID. You typically use this 
function only when you create submenus; you can create all your pull-down menus at 
once using the Get NewMBar function, and you can create pop-up menus using the 
standard pop-up control definition function. 





FUNCTION GetMenu (resourceID: Integer): MenuHandle; 





resourceID The resource ID of the 'MENU' resource that defines the characteristics of 
the menu. (You usually use the same number for a menu’s resource ID as 
the number that you specify for the menu ID in the menu resource.) 
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DESCRIPTION 


The GetMenu function creates a menu according to the specified menu resource, and it 
also creates a menu record for the menu. It reads the menu definition procedure 
(specified in the menu resource) into memory if it isn’t already in memory, and it stores 
a handle to the menu definition procedure in the menu record. The GetMenu function 
does not insert the newly created menu into the current menu list. 





After reading the 'MENU' resource, the GetMenu function searches for an 'mctb' 
resource with the same resource ID as the 'MENU' resource. If GetMenu finds this 
"mctb' resource, it uses the information in the 'mctb' resource to add entries for this 
menu to the application’s menu color information table. The GetMenu function uses 
SetMCEntries to add the entries defined by the 'mctb' resource to the application’s 
menu color information table. If GetMenu doesn’t find this 'mctb' resource, it uses the 
default colors specified in the menu bar entry of the application’s menu color 
information, or, if the menu bar entry doesn’t exist, it uses the standard colors for 

the menu. 








The GetMenu function returns a handle to the menu record of the menu. You can use the 
returned menu handle to refer to this menu in most Menu Manager routines. If GetMenu 
is unable to read the menu or menu definition procedure from the resource file, 
GetMenu returns NIL. 


After creating a menu with GetMenu, you can use AppendMenu, InsertMenuItem, 
AppendResMenu, or InsertResMenu to add more menu items to the menu if necessary. 


To add a menu created by GetMenu to a menu list, use the InsertMenu procedure. To 
update the menu bar with any new menu titles, use the DrawMenuBar procedure. 


Storing the definitions of your menus in resources (especially menu titles and menu 
items) makes your application easier to localize. 


A WARNING 
Menus in a resource must not be purgeable. « 


SPECIAL CONSIDERATIONS 


To release the memory associated with a menu that you read from a resource file using 
GetMenu, first call DeleteMenu to remove the menu from the menu list and to remove 
any menu title entry or menu item entries for this menu in the application’s menu color 
information table, then call the Resource Manager procedure ReleaseResource to 
dispose of the menu’s menu record. Use DrawMenuBar to update the menu bar. 





A WARNING 


Call GetMenu only once for a particular menu. If you need the handle of 
a menu currently in the menu list, use GetMenuHand1e or the Resource 
Manager function GetResource. A 
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For a description of the 'MENU' resource, see “The Menu Resource” on page 3-151; for a 
sample 'MENU' resource in Rez format, see Listing 3-2 on page 3-48. For information on 
the 'mctb' resource, see “The Menu Color Information Table Resource” on page 3-155. 


For details on how to add items to a menu, see the description of AppendMenu on 
page 3-124, InsertMenuItem on page 3-126, AppendResMenu on page 3-128, and 
InsertResMenu on page 3-129. To remove a menu, see the description of DeleteMenu 
on page 3-109. To update the menu bar, use the DrawMenuBar procedure, described on 
page 3-113. 





Adding Menus to and Removing Menus From the Current Menu List 


InsertMenu 
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After creating a menu with NewMenu or GetMenu, use the InsertMenu procedure to 
insert the menu into the current menu list. Use the Delet eMenu procedure to delete 
a menu from the current menu list; use the ClearMenuBar procedure to remove all 
menus from the current menu list. 





Use the InsertMenu procedure to insert an existing menu into the current menu list. 
PROCEDURE InsertMenu (theMenu: MenuHandle; beforeID: Integer); 


theMenu A handle to the menu record of the menu. The NewMenu and GetMenu 
functions return a handle to a menu record that you can use in this 
parameter. 


beforeID A number that indicates where in the current menu list the menu should 
be inserted. InsertMenu inserts the menu into the current menu list 
before the menu whose menu ID equals the number specified in the 
beforeID parameter. If the number in the beforeID parameter is 0 (or 
it isn’t the ID of any menu in the menu list), InsertMenu adds the new 
menu after all others (except before the Help, Keyboard, and Application 
menus). If the menu is already in the current menu list or the menu list is 
already full, InsertMenu does nothing. 


You can specify —1 for the beforeID parameter to insert a submenu into 
the current menu list. The submenus in the submenu portion of the menu 
list do not have to be currently associated with a hierarchical menu item; 
you can store submenus in the menu list and later specify that a menu 
item has a submenu if needed. However, note that the MenuKey function 
scans all menus in the menu list for keyboard equivalents, including 
submenus that are not associated with any menu item. You should not 
define keyboard equivalents for submenus that are in the current menu 
list but not associated with a menu item. 


Menu Manager Reference 


CHAPTER 3 


Menu Manager 


You can also specify —1 for the beforeID parameter to insert a pop-up 
menu into the current menu list. However, if you use the standard 
pop-up control definition function, the pop-up control automatically 
inserts the menu into the current menu list according to the needs of the 
pop-up control. 


DESCRIPTION 


The InsertMenu procedure inserts into the current menu list the menu identified by the 
specified handle to a menu record. To update the menu bar to reflect the new menu, use 
DrawMenuBar. 


SEE ALSO 


For details on how to update your application’s menu bar, see the description of 
DrawMenuBar on page 3-113. 


DeleteMenu 


Use the DeleteMenu procedure to delete an existing menu from the current menu list. 








PROCEDURE DeleteMenu (menuID: Integer); 











menuID The menu ID of the menu to delete from the current menu list. If the 
menu list does not contain a menu with the specified menu ID, 
DeleteMenu does nothing. 


DESCRIPTION 


The DeleteMenu procedure deletes the menu identified by the specified menu ID 
from the current menu list, and it removes all color entries for that menu from the 
application’s menu color information table. Delet eMenu does not release the memory 
occupied by the menu’s menu record. To release the memory occupied by the menu’s 
associated data structures, use DisposeMenu if you created the menu using NewMenu; 
use the Resource Manager procedure ReleaseResource if you created the menu using 
GetMenu or you read the resource in using Get NewMBar. 


The DeleteMenu procedure first checks the submenu portion of the current menu list 
for a menu ID with the specified ID. If it finds such a menu, it deletes that menu and 
returns. If DeleteMenu doesn’t find the menu in the submenu portion, it checks the 
regular portion of the current menu list. This allows a desk accessory to delete a 
submenu without deleting an application’s menu whose menu ID might conflict with 
the menu ID defined by a desk accessory. 


After deleting a menu, use DrawMenuBar to update the menu bar to reflect the changes 
to the current menu list. 
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SEE ALSO 


For details on how to dispose of a menu’s associated data structures using 
DisposeMenu, see “Disposing of Menus” on page 3-140. For information on the 
ReleaseResource procedure, see the chapter “Resource Manager” in Inside 
Macintosh: More Macintosh Toolbox. 





ClearMenuBar 


Use the ClearMenuBar procedure to delete all menus from the current menu list. 





PROCEDURE ClearMenuBar; 














DESCRIPTION 





The ClearMenuBar procedure deletes all menus from the current menu list and deletes 
all color entries from the application’s menu color information table. ClearMenuBar 
does not release the memory occupied by any of the menus’ menu records or the menu 
color information table. To release the memory occupied by the data structures 
associated with the menus, use DisposeMenu for each menu you created using 
NewMenu; use ReleaseResoutrce for each menu you created using GetMenu or if you 
read the resource in using Get NewMBar. 











After deleting all menus from the current menu list, use DrawMenuBar to update the 
appearance of the menu bar. 





SEE ALSO 
To update your application’s menu bar, see the description of DrawMenuBar on 
page 3-113. For information on the ReleaseResource procedure, see the chapter 
“Resource Manager” in Inside Macintosh: More Macintosh Toolbox. 





Getting a Menu Bar Description From an 'MBAR' Resource 


You usually create your application’s menu bar by doing the following: 





m defining the order and resource ID of your menus in an 'MBAR" resource 


m defining the menus in 'MENU' resources 





m reading in these descriptions using the Get NewMBar function 


m setting the current menu list to the menu list returned by GetNewMBar 





m updating the menu bar using DrawMenuBar 
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GetNewMBar 


DESCRIPTION 


Use the Get NewMBar function to read in the definition of a menu bar from an 'MBAR' 
resource. 


FUNCTION GetNewMBar (menuBarID: Integer): Handle; 





menuBarID The resource ID of an 'MBAR' resource that specifies the menus for a 
menu bar. 





The GetNewMBar function reads in the definition of a menu bar and its associated 
menus from an 'MBAR"' resource. The 'MBAR' resource identifies the order of menus 
contained in its menu bar. For each menu, it also specifies the menu’s resource ID. The 
GetNewMBar function reads in each menu from the 'MENU' resource with the resource 
ID specified in the 'MBAR" resource. 








The GetNewMBar function creates a menu list for the menu bar defined by the 'MBAR' 
resource and returns a handle to the menu list. (If the resource isn’t already in memory, 
GetNewMBar reads it into memory.) If Get NewMBar can’t read the resource, 
GetNewMBar returns NIL. Get NewMBar uses GetMenu to read in each individual menu. 











After reading in menus from an 'MBAR" resource, use SetMenuBar to make the menu 
list created by GetNewMBar the current menu list. Then use DrawMenuBar to update 
the menu bar. 





To release the memory occupied by the data structures associated with the menus ina 
menu list, use DisposeMenu for each menu you created using NewMenu; use the 
Resource Manager procedure Re leaseResource for each menu you created using 
GetMenu or if you read the resource in using Get NewMBar. To release the memory 
occupied by a menu list, use the Memory Manager procedure DisposeHandle. 





SPECIAL CONSIDERATIONS 


The Get NewMBar function first saves the current menu list and then clears the current 
menu list and your application’s menu color information table. It then creates a 

new menu list. Before returning a handle to the new menu list, the GetNewMBar 
function restores the current menu list to the previously saved menu list, but 
GetNewMBar does not restore the previous menu color information table. To save 

and then restore your application’s current menu color information table, call the 
GetMCInfo function before Get NewMBar and call the SetMCInfo procedure afterward. 











While you supply only the resource ID of an 'MBAR' resource to the GetNewMBar 
function, your application often needs to use the menu IDs defined in each of your 
menus’ 'MENU' resources. Most Menu Manager routines require either a menu ID 

or a handle to a menu record to perform operations on a specific menu. For menus in 
the current menu list, you can use the GetMenuHand1e function to get the handle to 
a menu record of a menu with a given menu ID. 
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For a description of the 'MENU' resource, see “The Menu Resource” on page 3-151; for a 
sample 'MENU' resource in Rez format, see Listing 3-2 on page 3-48. For a description of 
the 'MBAR' resource, see “The Menu Bar Resource” on page 3-155; for a sample 'MBAR' 
resource in Rez format, see Listing 3-4 on page 3-49. For information on the 'mctb' 
resource, see “The Menu Color Information Table Resource” on page 3-155. For 
information about the Resource Manager, see Inside Macintosh: More Macintosh Toolbox. 





Getting and Setting the Menu Bar 


You can use the GetMenuBar function to get a handle to a copy of the current menu list. 
Use the SetMenuBar procedure to set the current menu bar to a menu list previously 
returned by GetMenuBar or Get NewMBar. You can get the height of the menu bar using 
the GetMBarHeight function. 


GetMenuBar 


DESCRIPTION 


Use the GetMenuBar function to get a handle to a copy of the current menu list. 


FUNCTION GetMenuBar: Handle; 








The GetMenuBar function creates a copy of the current menu list and returns a handle 
to the copy. You can save the returned menu list and then add menus to or remove 
menus from the current menu list (using InsertMenu, DeleteMenu, or 
ClearMenuBar). You can later restore the saved menu list using SetMenuBar. 





To release the memory occupied by a saved menu list, use the Memory Manager’s 
DisposeHandle procedure. 


WARNING 

GetMenuBar doesn’t copy the menu records, just the menu list (which 
contains handles to the menu records). Do not dispose of any menus in a 
saved menu list if you wish to restore the menu list later. a 





SetMenuBar 
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Use the SetMenuBar procedure to set the current menu list to a specified menu list. 
PROCEDURE SetMenuBar (menuList: Handle); 
menuList A handle to a menu list that specifies the menus for a menu bar. You 


should specify a handle returned by GetMenuBar or Get NewMBar. 
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The SetMenuBar procedure copies the given menu list to the current menu list. As with 
GetMenuBar, SetMenuBar doesn’t copy the menu records, just the menu list (which 
contains handles to the menu records). 








You can use SetMenuBar to restore a menu list that you previously saved using 
GetMenuBar or to set the current menu list to a menu list created by Get NewMBar. 


The SetMenuBar procedure sets only the current menu list; to update the menu bar 
according to the new menu list, use the DrawMenuBar procedure. 


GetMBarHeight 


DESCRIPTION 


Use the GetMBarHeight function if you need to determine the current height of the 
menu bar. When the Roman script system is the current system script, the menu bar is 
20 pixels high. If a non-Roman script is the current system script, the menu bar may be 
greater than 20 pixels high to accommodate the current system font. 


FUNCTION GetMBarHeight: Integer; 





The GetMBarHeight function returns the current height, in pixels, of the menu bar. 


Drawing the Menu Bar 


Whenever your application adds menus to or removes menus from the current menu 
list, you should update the titles of the menus in the menu bar using the DrawMenuBar 
procedure. If you change the enabled state of a menu, you should call DrawMenuBar to 
update the menu title accordingly. Alternatively, you can use the InvalMenuBar 
procedure instead of DrawMenuBar to invalidate the menu bar; this causes the Event 
Manager to redraw the menu bar as part of its normal processing of update events. 





DrawMenuBar 


DESCRIPTION 


Use the DrawMenuBar procedure to draw the menu bar based on the current menu list. 


PROCEDURE DrawMenuBar; 





The DrawMenuBar procedure draws (or redraws) the menu bar according to the current 
menu list. You must call DrawMenuBar to update the menu bar after adding menus to or 
deleting menus from the current menu list using InsertMenu or DeleteMenu, after 
setting the current menu list using SetMenuBar, after changing the enabled state of a 
menu, or after any other routine that changes the current menu list. 
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InvalMenuBar 


DESCRIPTION 


Use the InvalMenuBar procedure to invalidate the menu bar. 


PROCEDURE InvalMenuBar; 





The InvalMenuBar procedure marks the menu bar as changed and in need 

of updating. When the Event Manager scans update regions for regions that require 
updating, the Event Manager also checks to determine whether the menu bar 

requires updating (because of a call to InvalMenuBar). If the menu bar needs updating, 
the Event Manager calls the DrawMenuBar procedure to draw the menu bar. 





You can use InvalMenuBar instead of DrawMenuBar to minimize blinking in the menu 
bar. For example, if you have several application-defined routines that can change the 
enabled state of a menu and each calls DrawMenuBar, you can replace the calls to 
DrawMenuBar with calls to InvalMenuBar. In this way the menu bar is redrawn only 
once instead of multiple times in quick succession. If you need to make immediate 
changes to the menu bar, use DrawMenuBar. If you want to redraw the menu bar at most 
once each time through your event loop, use InvalMenuBar. The InvalMenuBar 
procedure is available only in System 7. 





Responding to the User’s Choice of a Menu Command 
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When the user presses the mouse button while the cursor is in the menu bar, your 
application should call the MenuSelect function to allow the user to choose a 
command from the menu bar. If the user presses the mouse button while the cursor is 
over a pop-up menu that does not use the standard pop-up control definition function, 
your application should call the PopUpMenuSelect function to allow the user to make 
a choice from the pop-up menu. 


You should also allow the user to choose a menu command by typing a keyboard 
equivalent. When the user presses a key on the keyboard, your application should 
determine if the Command key was pressed at the same time, and, if so, your application 
should call the MenuKey function to map this keyboard combination to any 
corresponding Command-key equivalent. 


If the user chooses an item, both the MenuSelect and MenuKey functions highlight the 
title of the menu containing the chosen item and report the user’s choice to your 
application. Your application should perform the corresponding command and, when 
finished, should unhighlight the menu title using the Hil iteMenu procedure to indicate 
to the user that the command is completed. 


If the user releases the mouse button while the cursor is over a disabled item or types the 
keyboard equivalent of a disabled item, MenuSelect andMenuKey do not report the 
menu ID or menu item of the item. To determine if the user chose a disabled item (for 
example, so that your application can provide assistance to the user or explain to the 
user why the command is disabled), you can use the MenuChoice function to return the 
menu ID and menu item of the disabled menu command. 
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Your application should adjust its menus before calling MenuSelect or MenuKey. For 
example, you should enable or disable menu items as appropriate and add any 
applicable checkmarks or dashes to items that show attributes. 


Use the MenuSelect function to allow the user to choose a menu item from the menus 
in your application’s menu bar. 


FUNCTION MenuSelect (startPt: Point): LongInt; 


startPt The point (in global coordinates) representing the location of the cursor at 
the time the mouse button was pressed. 


When the user presses the mouse button while the cursor is in the menu bar, your 
application receives a mouse-down event. To handle mouse-down events in the menu 
bar, pass the location of the cursor at the time of the mouse-down event as the startPt 
parameter to MenuSelect. The MenuSelect function displays and removes menus as 
the user moves the cursor over menu titles in the menu bar, and it handles all user 
interaction until the user releases the mouse button. 


As the user drags the cursor through the menu bar, the MenuSelect function highlights 
the title of the menu the cursor is currently over and displays all items in that menu. If 
the user moves the cursor so that it is over a different menu, the MenuSelect function 
removes the previous menu and unhighlights its menu title. 


The MenuSelect function highlights and unhighlights menu items as the user drags the 
cursor over the items in a menu. The MenuSelect function highlights a menu item if 
the item is enabled and the cursor is currently over it; it removes such highlighting when 
the user moves the cursor to another menu item. The MenuSelect function does not 
highlight disabled menu items. 


If the user chooses an enabled menu item (including any item from a submenu), the 
MenuSelect function returns a value as its function result that indicates which menu 
and menu item the user chose. The high-order word of the function result contains the 
menu ID of the menu, and the low-order word contains the item number of the menu 
item chosen by the user. The MenuSelect function leaves the menu title highlighted; 
after performing the chosen task your application should unhighlight the menu title 
using the HiliteMenu procedure. 


If the user chooses an item from a submenu, MenuSelect returns the menu ID of the 
submenu in the high-order word and the item chosen by the user in the low-order word 
of its function result. The MenuSelect function also highlights the title of the menu in 
the menu bar that the user originally displayed in order to begin traversing to the 
submenu. After performing the chosen task, your application should unhighlight the 
menu title. 
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If the user releases the mouse button while the cursor is over a disabled item, in the 
menu bar, or outside of any menu, the MenuSelect function returns 0 in the high-order 
word of its function result and the low-order word is undefined. If it is necessary for 
your application to find the item number of the disabled item, your application can call 
MenuChoice to return the menu ID and menu item. 


If the user chooses an enabled item in a menu that a desk accessory has inserted into 
your application’s menu list, MenuSelect uses the SystemMenu procedure to process 
this occurrence and returns 0 to your application in the high-order word. 


SPECIAL CONSIDERATIONS 


When the MenuSelect function pulls down a menu, it stores the bits behind the menu 
as a relocatable object in the application heap of your application. 


ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 
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The InitMenus and InitProcMenu procedures initialize the MenuHook and 
MBarHook global variables to 0. If you choose, you can store the addresses of routines 
that MenuSelect calls in these global variables. The MenuHook global variable contains 
the address (if any) of a routine that MenuSelect calls repeatedly while the mouse 
button is down. MenuSelect does not pass any parameters to this routine. 


The MBarHook global variable contains the address (if any) of a routine that 
MenuSelect calls after a menu title is highlighted and the menu rectangle is calculated 
but before the menu is drawn. The menu rectangle is the rectangle (in global 
coordinates) in which the menu will be drawn. MenuSelect passes a pointer to the 
menu rectangle on the stack. If you provide the address of a routine in the MBarHook 
global variable, it should normally return 0 in the D0 register, indicating that 
MenuSelect should continue; returning 1 causes MenuSelect to cancel its operation 
and return immediately to the application. 





The MenuSelect function uses the global variable MBarEnab1le to determine if all 
menus in the current menu bar belong to a desk accessory or an application. If the 
MBarEnable global variable is nonzero, then all menus in the current menu bar belong 
to a desk accessory. If the MBarEnable global variable is 0, then all menus in the current 
menu bar belong to an application. If you’re writing a desk accessory, you may need to 
set the MBarEnable global variable to a nonzero value; if you’re writing an application, 
you should not change the value of the MBarEnable global variable. 











The global variable TheMenu contains the ID of the currently highlighted menu in the 
menu bar. If the user chooses an item from a submenu, TheMenu contains the menu ID 
of the submenu, not the menu to which the submenu is attached. 


For information on adjusting your application’s menus before calling MenuSelect, see 
“Adjusting the Menus of an Application” beginning on page 3-73. 
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See the description of the HiliteMenu procedure on page 3-119 for details on how to 
unhighlight a menu. For information on how to determine if the user chose a disabled 
item, see the description of the MenuChoice function on page 3-118. 


If the user presses another key while holding down the Command key, call the MenuKey 
function to determine if the keyboard combination maps to the keyboard equivalent of a 
menu item in a menu in the current menu list. 


FUNCTION Menukey (ch: Char): LongInt; 


ch The 1-byte character representing the key pressed by the user in 
combination with the Command key. 


The MenuKey function maps the given character to the menu and menu item with that 
keyboard equivalent. The MenuKey function returns as its function result a value that 
indicates the menu ID and menu item that has the keyboard equivalent corresponding to 
the given character. 


The MenuKey function does not distinguish between uppercase and lowercase letters. It 
takes the 1-byte character passed to it and calls the UpperText procedure (which 
provides localizable uppercase conversion of the character). Thus, MenuKey translates 
any lowercase character to uppercase when comparing a keyboard event to keyboard 
equivalents. This allows a user to invoke a keyboard equivalent command, such as the 
Copy command, by pressing the Command key and “c” or “C”. For consistency between 
applications, you should define the keyboard equivalents of your commands so that they 


appear in uppercase in your menus. 


If the given character maps to an enabled menu item in the current menu list, MenuKey 
highlights the menu title of the chosen menu, returns the menu ID in the high-order 
word of its function result, and returns the chosen menu item in the low-order word of 
its function result. After performing the chosen task, your application should 
unhighlight the menu title using the HiliteMenu procedure. 


If the given character does not map to an enabled menu item in the current menu list, 
MenuKey returns 0 in its high-order word and the low-order word is undefined. 


If the given character maps to a menu item in a menu that a desk accessory has inserted 
into your application’s menu list, MenuSelect uses the Syst emMenu procedure to 
process this occurrence and returns 0 to your application in the high-order word. 


You should not define menu items with identical keyboard equivalents. The MenuKey 
function scans the menus from right to left and the items from top to bottom. If you have 
defined more than one menu item with identical keyboard equivalents, MenuKey returns 
the first one it finds. 
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The MenuKey function first searches the regular portion of the current menu list for a 
menu item with a keyboard equivalent matching the given key. If it doesn’t find one 
there, it searches the submenu portion of the current menu list. If the given key maps to 
a menu item in a submenu, Menukey highlights the menu title in the menu bar that the 
user would normally pull down to begin traversing to the submenu. Your application 
should perform the desired command and then unhighlight the menu title. 


You shouldn’t assign a Command-Shift-number key sequence to a menu item as its 
keyboard equivalent; Command-Shift-number key sequences are reserved for use as 
'FKEY' resources. Command-Shift-number key sequences are not returned to your 
application, but instead are processed by the Event Manager. The Event Manager 
invokes the 'FKEY' resource with a resource ID that corresponds to the number that 
activates it. 








Apple reserves the Command-key codes $1B (Control-[ ) through $1F (Control-_) to 
indicate meanings other than keyboard equivalents. MenuKey ignores these character 
codes and returns a function result of 0 if you specify any of these values in the ch 
parameter. Your application should not use these character codes for its own use. 


The global variable TheMenu contains the ID of the currently highlighted menu in the 
menu bar. If the user chooses an item from a submenu, TheMenu contains the menu ID 
of the submenu, not the menu to which the submenu is attached. 


WARNING 

Do not define a “circular” hierarchical menu—that is, a hierarchical 
menu in which a submenu has a submenu whose submenu is 

a hierarchical menu higher in the chain. If MenuKey detects a circular 
hierarchical menu, it creates a system error with error number 86. A 


To unhighlight a menu, use the HiliteMenu procedure, described on page 3-119. To 
provide support for keyboard equivalents other than Command-key equivalents, see the 
discussion of 'KCHR' resources in Inside Macintosh: Text. 


MenuChoice 


DESCRIPTION 
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If your application needs to find the item number of a disabled menu item that the 
user attempted to choose, you can use the MenuChoice function to return the chosen 
menu item. 


FUNCTION MenuChoice: LongInt; 


If the user chooses a disabled menu item, the MenuChoice function returns a value that 
indicates which menu and menu item the user chose. The high-order word of the 
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function result contains the menu ID of the menu, and the low-order word contains the 
item number of the menu item chosen by the user. 


The MenuChoice function returns 0 as the low-order word of its function result if the 
mouse button was released while the cursor was in the menu bar or outside the menu. 


SPECIAL CONSIDERATIONS 


The Menu Manager updates the global variable MenuDisable whenever a menu is 
displayed. As the user moves the cursor over each item, the Menu Manager calls the 
menu definition procedure of the menu to update the MenuDisabl1e global variable to 
reflect the current menu ID and menu item. The standard menu definition procedure 
updates the global variable MenuDisable appropriately. If your application uses its 
own menu definition procedure, your menu definition procedure should support this 
feature; if you use a menu definition procedure that does not update the global variable 
MenuDisable appropriately, the result returned by MenuChoice is undefined. 


HiliteMenu 


You can use the Hil iteMenu procedure to highlight or unhighlight menu titles. For 
example, after performing a menu command chosen by the user, use the HiliteMenu 
procedure to unhighlight the menu title. 














PROCEDURE HiliteMenu (menuID: Integer); 


menuID The menu ID of the menu whose title should be highlighted. If the menu 
title of the specified menu is already highlighted, HiliteMenu does 
nothing. If the menu ID is 0 or the specified menu ID isn’t in the current 
menu list, HiliteMenu unhighlights whichever menu title is currently 
highlighted (if any). 


DESCRIPTION 


The MenuSelect and Menukey functions highlight the title of the menu containing 
the item chosen by the user. After performing the chosen task, your application 
should unhighlight the menu title by calling HiliteMenu and passing 0 in the 
menulID parameter. 


The HiliteMenu procedure highlights a menu title by first saving the bits behind the 
title rectangle and then drawing the highlighted title. HiliteMenu unhighlights a menu 
title by restoring the bits behind the menu title. 


The global variable TheMenu contains the ID of the currently highlighted menu in the 
menu bar. If the user chooses an item from a submenu, TheMenu contains the menu ID 
of the submenu, not the menu to which the submenu is attached. 
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To highlight the entire menu bar, use the FlashMenuBar procedure, described on 
page 3-141. 


PopUpMenuSelect 


DESCRIPTION 
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To display a pop-up menu without using the standard pop-up control definition 
function, use the PopUpMenuSelect function to display the pop-up menu anywhere 
on the screen. If your application uses the standard pop-up control definition function, 
your application does not need to use PopUpMenuSelect. 





FUNCTION PopUpMenuSelect (menu: MenuHandle; 
Top: Integer; Left: Integer; 
PopUpiItem: Integer) 
LongInt; 


menu A handle to the menu record of the menu. The NewMenu, GetMenu, and 
GetMenuHand_1e functions return a handle to a specified menu’s menu 
record. 

Top The top coordinate of the pop-up box when it is closed. This value should 
be in global coordinates. 


Left The left coordinate of the pop-up box when it is closed. This value should 
be in global coordinates. 


PopUpItem The item number of the current item minus 1. This value should 
correspond to the user’s previous choice from this menu. If the user has 
not previously made a choice, this value should be set to the default value. 


The PopUpMenuSelect function uses the location specified by the Top and Left 
parameters to determine where to display the specified item of the pop-up menu. The 
PopUpMenuSelect function displays the pop-up menu so that the menu item specified 
in the PopUpItem parameter appears highlighted at the specified location. Figure 3-24 
on page 3-34 shows the pop-up title and pop-up box of a pop-up menu. 





The PopUpMenuSelect function highlights and unhighlights menu items and handles 
all user interaction until the user releases the mouse button. The PopUpMenuSelect 
function returns the menu ID of the chosen menu in the high-order word of its function 
result and the chosen menu item in the low-order word. 


Your application is responsible for highlighting the pop-up title, setting the mark of the 
current menu item appropriately, and drawing the text and downward-pointing 
indicator in the pop-up box before calling PopUpMenuSelect. Your application should 
also make sure the pop-up menu is in the submenu portion of the current menu list 
before calling PopUpMenuSelect. (You can use the InsertMenu procedure and specify 
-1in the beforeID parameter to insert the pop-up menu into the current menu list.) 
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After calling PopUpMenuSelect, your application can delete the pop-up menu from the 
current menu list or leave it in the current menu list. 


Your application is also responsible for storing the current value of the menu item, 
drawing the text and downward-pointing indicator in the pop-up box, and 
unhighlighting the pop-up title after calling PopUpMenuSelect. If you use the standard 
pop-up control definition function, these actions are performed for you by the pop-up 
control and your application does not need to call PopUpMenuSelect. 


When implementing pop-up menus, you should follow the guidelines for pop-up menus 
described in Macintosh Human Interface Guidelines. For example, you should define the 
pop-up box of your pop-up menu as a rectangle that is the same height as a menu item, 
with a one-pixel drop shadow, and should make the pop-up box wide enough to show 
the currently selected item and a downward-pointing indicator. 


SystemMenu 


DESCRIPTION 


The MenuSelect and MenuKey functions call the Syst emMenu procedure when the 
user chooses an item in a menu that belongs to a desk accessory launched in your 
application’s partition. Your application should not need to call the SystemMenu 
procedure. 


PROCEDURE SystemMenu (menuResult: LongInt); 


menuResult The value that indicates the menu and menu item chosen by the user. The 
menu ID is in the high-order word, and the menu item is in the low-order 
word. The menu ID for a menu belonging to a desk accessory is a 
negative number. 


The SystemMenu procedure directs the desk accessory to perform the appropriate action 
for the given menu item by calling the desk accessory’s control routine and passing the 
accMenu constant in the csCode parameter. The desk accessory should perform the 
desired action and return. See Inside Macintosh: Devices for more information on desk 
accessories. 


ASSEMBLY-LANGUAGE INFORMATION 





If you're writing a desk accessory, you may need to set the MBarEnable global variable 
to appropriate values. If the MBarEnab1e global variable is nonzero, then all menus in 
the current menu bar belong to a desk accessory. If the MBarEnab1e global variable is 0, 
then all menus in the current menu bar belong to an application. If you’re writing an 
application, you should not change the value of the MBarEnable global variable. 
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SystemEdit 


When the user chooses one of the standard editing commands in the Edit menu (Undo, 
Cut, Copy, Paste, and Clear), call the SystemEdit function to determine whether the 
active window belongs to a desk accessory that is launched in your application’s 
partition. If so, the SystemEdit function directs the desk accessory to perform the 
editing command and returns TRUE. If the active window does not belong to a desk 
accessory launched in your application’s partition, SystemEdit returns FALSE and 
your application should process the command. 











FUNCTION SystemEdit (editCmd: Integer): Boolean; 





editCmd The item number of the standard editing command chosen by the user. 


Getting a Handle to a Menu Record 


Most Menu Manager routines that manage menus require that you specify a handle to 


the menu record of the menu on which you want to perform an operation. You can use 
the HMGet HelpMenuHand1e function to get a handle to your application’s Help menu. 
Use the GetMenuHand1e function to get a handle to the menu record of any of your 
application’s other pull-down menus or submenus in the current menu list. For pop-up 
menus that use the standard control definition function, you can access the control 
record to get the menu’s handle. 


GetMenuHandle 


DESCRIPTION 
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You can use the Get MenuHand_1e function to get a handle to the menu record of any of 
your application’s menus other than its Help menu. (Use the HMGetHelpMenuHandle 
function to get a handle to the menu record of your application’s Help menu.) The 
GetMenuHandle function is also available as the GetMHand1e function. 


FUNCTION GetMenuHandle (menuID: Integer): MenuHandle; 


menuID The menu ID of the menu. (Note that this is not the resource ID, 
although you often assign the menu ID so that it matches the resource 
ID.) You assign a menu ID in the 'MENU' resource of a menu. If you 
do not define your menus in 'MENU" resources, you can assign a menu 
ID using NewMenu. 








The GetMenuHand1e function returns a handle to the menu record of the menu having 
the specified menu ID. If the menu is in the current menu list, GetMenuHand1e returns 
a handle to the menu record of the menu as its function result. Otherwise, 
GetMenuHand1e returns NIL as its function result. 
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SPECIAL CONSIDERATIONS 


To get a handle to a menu record of a pop-up menu that you create using the pop-up 
control definition function, dereference the cnt rlData field of the pop-up menu’s 
control record instead of using GetMenuHandle. 


HMGetHelpMenuHandle 


DESCRIPTION 


Use the HMGet Hel pMenuHand1e function to get a handle to the menu record of your 
application’s Help menu. 


FUNCTION HMGetHelpMenuHandle (VAR mh: MenuHandle): OSErr; 





mh The HMGet HelpMenuHand_1e function returns a copy of a handle to your 
application’s Help menu in this parameter. 


The HMGet HelpMenuHand_1e function returns in the mh parameter a copy of a handle to 
the menu record of your application’s Help menu. With this handle, you can append 
items to your application’s Help menu by using the AppendMenu procedure or other 
related Menu Manager routines. The Help Manager automatically adds the divider that 
separates your items from the rest of the Help menu items. 


Be sure to define help balloons for your items in the Help menu by creating an 'hmnu' 
resource and specifying the kHMHelpMenuID constant as its resource ID. 


The Menu Manager functions MenuSelect and MenukKey return a result with the menu 
ID in the high-order word and the menu item in the low-order word. The MenuSelect 
function (and the MenuKey function, if the user chooses an item with a keyboard 
equivalent) returns the kHMHe1pMenuID constant in the high-order word when the user 
chooses an appended item from the Help menu. The menu item number of the 
appended menu item is returned in the low-order word of the function result. Apple 
reserves the right to change the number of standard items in the Help menu. To 
determine the number of items in the Help menu, call the CountMItems function. 


SPECIAL CONSIDERATIONS 


RESULT CODES 


Do not use the GetMenuHand_1e function to get a handle to the menu record of the Help 
menu. GetMenuHand1e returns a handle to the menu record of the global Help menu, 
not the menu record of the Help menu that is specific to your application. 








noErr 0 No error 

paramErr —50 Error in parameter list 
memFullErr -108 Not enough room in heap zone 
resNotFound -192 Unable to read resource 
hmHelpManagerNotInited -855 Help menu not set up 
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For examples of how to add items to your application’s Help menu and how to handle 
the user’s choice of an item in the Help menu, see Listing 3-14 on page 3-68 and 
Listing 3-26 on page 3-81. See the chapter “Help Manager” in Inside Macintosh: More 
Macintosh Toolbox for information on creating help balloons for the menus of 

your application. 


Adding and Deleting Menu Items 


You can add the names of all resources of a specified type to a menu using the 
InsertResMenu or AppendResMenu procedure. You can add menu items that you 
define to a menu using the AppendMenu or InsertMenuItem procedure. You can also 
delete menu items using the DeleteMenuItem procedure. In most cases you should 

not insert or delete individual menu items from an already existing menu unless the user 
expects a menu (such as a list of currently open documents) to change. 


If you add menu items using the AppendMenu or InsertMenulItem procedure, you 
should define in resources the text and other characteristics of the menu items that you 
add. This makes your application easier to localize for other regions. 


AppendMenu 


DESCRIPTION 


3-124 


Use the AppendMenu procedure to append one or more items to a menu previously 
created using NewMenu, GetMenu, or Get NewMBar. 


PROCEDURE AppendMenu (menu: MenuHandle; data: Str255); 





menu A handle to the menu record of the menu to which you wish to append 
the menu item or items. 

data A string that defines the characteristics of the new menu item or items. 
Note that in most cases you should store the text of a menu item in a 
resource, so that your menu items can be more easily localized. The 
AppendMenu procedure appends the menu items in the order in which 
they are listed in the data parameter. 


The AppendMenu procedure appends any defined menu items to the specified menu. 

The menu items are added to the end of the menu. You specify the text of any menu 
items and their characteristics in the data parameter. You can embed metacharacters in 
the string to define various characteristics of a menu item. 
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Here are the metacharacters that you can specify in the data parameter: 


Metacharacter Description 
; or Return Separates menu items. 


0 When followed by an icon number, defines the icon for the item. If the 
keyboard equivalent field contains $1C, this number is interpreted as 
a script code. 


! When followed by a character, defines the mark for the item. If the 
keyboard equivalent field contains $1B, this value is interpreted as 
the menu ID of a submenu of this menu item. 


< When followed by one or more of the characters B, I, U, O, and S, 
defines the character style of the item to Bold, Italic, Underline, 
Outline, or Shadow, respectively. 


/ When followed by a character, defines the keyboard equivalent for 
the item. When followed by $1B, specifies that this menu item has a 
submenu. To specify that the menu item has a script code, small icon, 
or reduced icon, use the Set ItemCmd procedure to set the keyboard 
equivalent field to $1C, $1D, or $1E, respectively. 


( Defines the menu item as disabled. 


You can specify any, all, or none of these metacharacters in the text string. The 
metacharacters that you specify aren’t displayed in the menu item. (To use any of these 
metacharacters in the text of a menu item, first use AppendMenu, specifying at least one 
character as the item’s text, and then use the SetMenuItemText procedure to set the 
item’s text to the desired string.) 


Note 

If you add menu items using the AppendMenu procedure, you should 
define the text and any marks or keyboard equivalents in resources for 
easier localization. # 


You can specify the first character that defines the text of a menu item as a hyphen to 
create a divider line. The string in the data parameter can be blank (containing one or 
more spaces), but it should not be an empty string. 


If you do not define a specific characteristic of a menu item, the AppendMenu procedure 
assigns the default characteristic to the menu item. If you do not define any characteristic 
other than the text for a menu item, the AppendMenu procedure inserts the menu item so 
that it appears in the menu as an enabled item, without an icon or a mark, in the plain 
character style, and without a keyboard equivalent. 


You can use AppendMenu to append items to a menu regardless of whether the menu is 
in the current menu list. 


See “Adding Items to a Menu” on page 3-64 for examples of appending items to a menu. 
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InsertMenultem 


DESCRIPTION 
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Use the InsertMenuItem procedure to insert one or more items to a menu previously 
created using NewMenu, GetMenu, or Get NewMBar. 


The InsertMenuItem procedure is also available as the InsMenuItem procedure. 











PROCEDURE InsertMenulItem (theMenu: MenuHandle; itemString: Str255; 








afterItem: Integer); 


theMenu A handle to the menu record of the menu to which you wish to add the 
menu item or items. 


itemString 
A string that defines the characteristics of the new menu items. Note that 
in most cases you should store the text of a menu item in a resource, so 
that your menu items can be more easily localized. You can specify the 
contents of the itemSt ring parameter using metacharacters; the 
InsertMenuItem procedure accepts the same metacharacters as the 
AppendMenu procedure. However, if you specify multiple items, the 
InsertMenultem procedure inserts the items in the reverse of their 
order in the itemString parameter. 


afterItem The item number of the menu item after which the new menu items are to 
be added. Specify 0 in the afterItem parameter to insert the new items 
before the first menu item; specify the item number of a current menu 
item to insert the new menu items after it; specify a number greater than 
or equal to the last item in the menu to append the new items to the end 
of the menu. 


The InsertMenuItem procedure inserts any defined menu items to the specified menu. 
The menu items are inserted according to the location specified by the afterItem 
parameter. You specify the text of any menu items and their characteristics in the 
itemString parameter. You can embed metacharacters in the string you specify to 
define various characteristics of a menu item. The metacharacters aren’t displayed in 
the menu. 


Here are the metacharacters you can specify in the itemSt ring parameter: 


Metacharacter Description 


; or Return Separates menu items. 


A 


When followed by an icon number, defines the icon for the item. If the 
keyboard equivalent field contains $1C, this number is interpreted as 
a script code. 


! When followed by a character, defines the mark for the item. If the 
keyboard equivalent field contains $1B, this value is interpreted as 
the menu ID of a submenu of this menu item. 
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Metacharacter Description 


< When followed by one or more of the characters B, I, U, O, and S, 
defines the character style of the item to Bold, Italic, Underline, 
Outline, or Shadow, respectively. 


/ When followed by a character, defines the keyboard equivalent for 
the item. When followed by $1B, specifies that this menu item has a 
submenu. To specify that the menu item has a script code, small icon, 
or reduced icon, use the Set ItemCmd procedure to set the keyboard 
equivalent field to $1C, $1D, or $1E, respectively. 


( Defines the menu item as disabled. 


You can specify any, all, or none of these metacharacters in the text string. The 
metacharacters that you specify aren’t displayed in the menu item. To use any of these 
metacharacters in the text of a menu item, first use InsertMenuItem, specifying at least 
one character as the item’s text, and then use the SetMenuItemText procedure to set 
the item’s text to the desired string. 


Note 

If you add menu items using the InsertMenuItem procedure, you 
should define the text and any marks or keyboard equivalents in 
resources for easier localization. # 


You can specify the first character that defines the text of a menu item as a hyphen to 
create a divider line. The string in the itemString parameter can be blank (containing 
one or more spaces), but it should not be an empty string. 


If you do not define a specific characteristic of a menu item, the InsertMenuItem 
procedure assigns the default characteristic to the menu item. If you do not define any 
characteristic other than the text for a menu item, the InsertMenuItem procedure 
inserts the menu item so that it appears in the menu as an enabled item, without an icon 
or a mark, in the plain character style, and without a keyboard equivalent. 


You can use InsertMenuItem to insert items into a menu regardless of whether the 
menu is in the current menu list. 


See “Adding Items to a Menu” beginning on page 3-64 for examples. 


DeleteMenultem 


Use the Delet eMenuItem procedure to delete an item from a menu. The 
DeleteMenuItem procedure is also available as the De1MenulItem procedure. 





PROCEDURE DeleteMenuItem (theMenu: MenuHandle; item: Integer); 
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theMenu A handle to the menu record of the menu from which you want to delete 
the menu item. 

item The item number of the menu item to delete. If you specify 0 or a number 
greater than the last item in the menu, Delet eMenuItem does not delete 
any item from the menu. 


The DeleteMenuItem procedure deletes a specified menu item from a menu. The 
DeleteMenulItem procedure also deletes the item’s menu item entry from your 
application’s menu color information table (if an entry exists). You should not delete 
items from an existing menu unless the user expects the menu (such as a menu that lists 
open documents) to change. 


AppendResMenu 


DESCRIPTION 
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Use the AppendResMenu procedure to search all resource files open to your application 
for a given resource type and to append the names of any resources it finds to a specified 
menu. The specified menu must have been previously created using NewMenu, 

GetMenu, or GetNewMBar. 


The AppendResMenu procedure is also available as the AddResMenu procedure. 








PROCEDURE AppendResMenu (theMenu: MenuHandle; theType: ResType) ; 


theMenu A handle to the menu record of the menu to which to append the names 
of any resources of a given type that AppendResMenu finds. 


theType A four-character code that identifies the resource type for which to search. 


The AppendResMenu procedure searches all resource files open to your application for 
resources of the type defined by the parameter theType. It appends the names of any 
resources it finds of the given type to the end of the specified menu. AppendResMenu 
appends the names of found resources in alphabetical order; it does not alphabetize 
items already in the menu. The AppendResMenu procedure does not add resources with 
names that begin with a period (.) or a percent sign (%) to the menu. 


The AppendResMenu procedure assigns default characteristics to each menu item. Each 
appended menu item appears in the menu as an enabled item, without an icon or a 
mark, in the plain character style, and without a keyboard equivalent. To get the name or 
to change other characteristics of an item appended by AppendResMenu, use the Menu 
Manager routines described in “Getting and Setting the Appearance of Menu Items” 
beginning on page 3-130. 
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If you specify that AppendResMenu add resources of type 'DRVR' to your Apple menu, 
AppendResMenu adds the name (and icon) of each item in the Apple Menu Items folder 
to the menu. 


If you specify that AppendResMenu append resources of type 'FONT' or 'FOND', the 
Menu Manager performs special processing for any resources it finds that have font 
numbers greater than $4000. If the script system associated with the font name is 
installed in the system, AppendResMenu stores information in the itemDefinitions 
array (in the itemIcon and itemCmd fields for that item) in the menu’s menu record. 
This allows the Menu Manager to display the font name in the correct script. 


SPECIAL CONSIDERATIONS 


The AppendResMenu procedure calls the Resource Manager procedure SetResLoad 
(specifying TRUE in the load parameter) before returning. The AppendResMenu 
procedure reads the resource data of the resources it finds into memory. If your 
application does not want the Resource Manager to read resource data into memory 
when your application calls other routines that read resources, you need to call 
SetResLoad and specify FALSE in the load parameter after AppendResMenu returns. 





SEE ALSO 
Listing 3-15 on page 3-69 shows a sample that adds items from the Apple Menu Items 
folder to the Apple menu, and Listing 3-16 on page 3-70 shows a sample that adds font 
names to a menu. See Inside Macintosh: More Macintosh Toolbox for information on the 
Resource Manager. 

InsertResMenu 


Use the InsertResMenu procedure to search all resource files open to your application 
for a given resource type and to insert the names of any resources it finds to a specified 
menu. The items are inserted after the specified menu item. The specified menu must 
have been previously created using NewMenu, GetMenu, or GetNewMBar. 


PROCEDURE InsertResMenu (theMenu: MenuHandle; theType: ResType; 
afterItem: Integer); 








theMenu A handle to the menu record of the menu to which to add the names of 
any resources of a given type that InsertResMenu finds. 


theType A four-character code that identifies the resource type for which to search. 


afterItem A number that indicates where in the menu to insert the names of any 
resources of the given type that Insert ResMenu finds. Specify 0 in the 
afterItem parameter to insert the items before the first menu item; 
specify the item number of a menu item already in the menu to insert the 
items after the specified item number. If you specify a number greater 
than or equal to the last item in the menu, the items are inserted at the 
end of the menu. 
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The InsertResMenu procedure searches all resource files open to your application for 
resources of the type defined by the parameter theType. It inserts the names of any 
resources it finds of the given type at the specified location in the specified menu. 
InsertResMenu adds the names of found resources in alphabetical order; it does not 
alphabetize items already in the menu. 


The InsertResMenu procedure does not add resources with names that begin with a 
period (.) or a percent sign (%) to the menu. 


The InsertResMenu procedure assigns default characteristics to each menu item. Each 
appended menu item appears in the menu as an enabled item, without an icon or a 
mark, in the plain character style, and without a keyboard equivalent. To get the name or 
to change other characteristics of an item appended by InsertResMenu, use the Menu 
Manager routines described in the next section, “Getting and Setting the Appearance of 
Menu Items.” 


If you specify that InsertResMenu add resources of type 'DRVR' to your Apple menu, 
InsertResMenu adds the name (and icon) of each item in the Apple Menu Items folder 
to the menu. 


If you specify that InsertResMenu add resources of type 'FONT' or 'FOND", the 
Menu Manager performs special processing for any resources it finds that have font 
numbers greater than $4000. If the script associated with the font name is currently 
active, InsertResMenu stores information in the itemDefinitions array (in the 
itemIcon and itemCmd fields for that item) in the menu’s menu record that allows the 
Menu Manager to display the font name in the correct script. 


SPECIAL CONSIDERATIONS 


The InsertResMenu procedure calls the Resource Manager procedure SetResLoad 
(specifying TRUE in the load parameter) before returning. The InsertResMenu 
procedure reads the resource data of the resources it finds into memory. If your 
application does not want the Resource Manager to read resource data into memory 
when your application calls other routines that read resources, you need to call 
SetResLoad and specify FALSE in the load parameter after InsertResMenu returns. 


Getting and Setting the Appearance of Menu Items 
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You can get information about the characteristics of a menu item using Menu Manager 
routines. For example, you can get an item’s text, style, mark, keyboard equivalent, 
script code, and associated icons. You can also determine if a menu item has a submenu 
associated with it and the menu ID of the submenu. 


You can set the characteristics of a menu item, including associating a submenu with a 
menu item, using Menu Manager routines. Whenever possible, however, you should 
define your application’s menu items in 'MENU' resources. This makes your application 
easier to localize for other regions. 


You can also enable and disable menu items or entire menus using Menu Manager 
routines. 
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EnableItem 


Use the EnableItem procedure to enable a menu item or a menu. 











PROCEDURE EnableItem (theMenu: MenuHandle; item: Integer); 








theMenu A handle to the menu record of the menu containing the menu item 
to enable. 

item The item number of the menu item to enable, or 0 to enable the entire 
menu. You cannot individually enable a menu item with an item number 
greater than 31. 





If you specify 0 in the item parameter, the EnableItem procedure 
enables the menu title and all items in the menu that were not previously 
individually disabled. 


DESCRIPTION 


The EnableItem procedure enables a specified menu item so that it no longer appears 
dim and so that the user can choose the menu item. 





Note that, if you enable a menu, the EnableItem procedure enables the menu title but 
only enables those menu items that are not currently disabled as a result of your 
application previously calling DisableItemand specifying each item’s item number. 
For example, if all items in your application’s Edit menu are enabled, you can disable the 
Cut and Copy commands individually using DisableItem. If you choose to disable the 
entire menu by passing 0 as the item parameter to DisableItem, the menu and all its 
items are disabled. If you then enable the entire menu by passing 0 as the item 
parameter to EnableItem, the menu and its items are enabled, except for the Cut and 
Copy commands, which remain disabled. In this case, to enable the Cut and Copy 
commands you must enable each one individually using EnableItem. 








If your application enables a menu using EnableItem, it should call DrawMenuBar to 
update the menu bar’s appearance. 


SEE ALSO 
See “Enabling and Disabling Menu Items” on page 3-58 for examples of enabling items 
in a menu. 

DisableItem 


Use the DisableItem procedure to disable a menu item or an entire menu. 


PROCEDURE DisableItem (theMenu: MenuHandle; item: Integer); 
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theMenu A handle to the menu record of the menu containing the menu item 
to disable. 

item The item number of the menu item to disable, or 0 to disable the entire 
menu. You cannot individually disable a menu item with an item number 
greater than 31. 


If you specify 0 in the item parameter, the DisableItem procedure 
disables the menu title and all items in the menu, including menu items 
with item numbers greater than 31. 


The DisableItem procedure disables a specified menu item so that it appears dim and 
cannot be chosen by the user. 


If your application disables a menu using DisableItem, your application should call 
DrawMenuBar to update the menu bar’s appearance. 


See “Enabling and Disabling Menu Items” on page 3-58 for examples of disabling items 
in a menu. 


GetMenultemText 


DESCRIPTION 
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Use the GetMenuItemText procedure to get the text of a specific menu item. The 
GetMenultemText procedure is also available as the Get Item procedure. 


PROCEDURE GetMenulItemText (theMenu: MenuHandle; item: Integer; 
VAR itemString: Str255); 


theMenu A handle to the menu record of the menu containing the menu item 
whose text you wish to get. 


item The item number of the menu item. The GetMenuItemText procedure 
returns the text of this item. 


itemString The GetMenuItemText procedure returns the text of the menu item in 
this parameter. 


The GetMenulItemText procedure returns the text of the specified menu item in the 
itemString parameter. Use other Menu Manager routines to get information about 
the other characteristics of a menu item. 
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SetMenultemText 


DESCRIPTION 
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Use the SetMenuItemText procedure to set the text of a specific menu item to a given 
string. The SetMenuItemText procedure is also available as the Set Item procedure. 


PROCEDURE SetMenulItemText (theMenu: MenuHandle; item: Integer; 
itemString: Str255); 


theMenu A handle to the menu record of the menu containing the menu item 
whose text you wish you to set. 


item The item number of the menu item. The SetMenuItemText procedure 
sets the text of this item. 


itemString The SetMenuItemText procedure sets the text of the menu item 
according to the string specified in the itemSt ring parameter. The 
SetMenuItemText procedure does not recognize metacharacters or set 
any other characteristics of the menu item. The itemSt ring parameter 
can be blank, but it should not be an empty string. 


The SetMenuItemText procedure sets the text of the specified menu item to the text 
specified in the itemString parameter. The SetMenuItemText procedure does not 
recognize any metacharacters used by the AppendMenu and InsertMenuItem 
procedures. Use other Menu Manager routines to set other characteristics of a menu item. 


If you set the text of a menu item using the SetMenuItemText procedure, you should 
store the text in a string resource so that your application can be more easily localized. 


See Listing 3-9 on page 3-59 for an example of setting the text of a menu item. 


GetItemStyle 


Use the Get ItemStyle procedure to get the style of the text in a specific menu item. 








PROCEDURE GetItemStyle (theMenu: MenuHandle; item: Integer; 
VAR chStyle: Style); 


theMenu A handle to the menu record of the menu containing the menu item 
whose style you wish to get. 


item The item number of the menu item. The Get ItemSt yle procedure 
returns the style of the text for this item. 
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chStyle 


The Get ItemStyle procedure returns the style of the text for this item in 
the chStyle parameter. The chStyle parameter is a set defined by the 
Style data type. 





TYPE 

StyleItem = (bold, italic, underline, outline, 
shadow, condense, extend); 

Style = SET OF StyleItem; 


The Get ItemStyle procedure returns the style of the text of the specified menu item in 
the chStyle parameter. The returned style can be one or more of the styles defined by 
the Style data type, or it is the empty set if the style of the text is Plain. 


SetItemStyle 


DESCRIPTION 


SEE ALSO 
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Use the Set ItemStyle procedure to set the style of the text in a specific menu item. 





PROCEDURE 











theMenu 


item 


chStyle 





SetItemStyle (theMenu: MenuHandle; item: Integer; 


chStyle: Style); 


A handle to the menu record of the menu containing the menu item 
whose style you wish to set. 


The item number of the menu item. The Set ItemStyle procedure sets 
the style of the text for this item. 


The Set ItemStyle procedure sets the style of the text for this item 
according to the style described by the chStyle parameter. The 
chStyle parameter is a set defined by the Style data type. 


TYPE 


StyleItem = (bold, italic, underline, outline, 
shadow, condense, extend); 
Style = SET OF StyleItem; 


You can set the style to one or more of the styles defined by the Style 
data type, or you can set it to Plain by specifying an empty set in the 
chStyle parameter. 


The Set ItemStyle procedure sets the style of the text of the specified menu item to the 
style or styles defined by the chStyle parameter. 


See Listing 3-10 on page 3-60 for examples of setting the style of a menu item. 
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GetItemMark 


Use the Get ItemMark procedure to get the mark of a specific menu item or the menu ID 
of the submenu associated with the menu item. 


PROCEDURE GetItemMark (theMenu: MenuHandle; item: Integer; 
VAR markChar: Char); 


theMenu A handle to the menu record of the menu containing the menu item 
whose mark or submenu you wish to get. 


item The item number of the menu item. The Get ItemMark procedure returns 
the mark of this item or, if this item has a submenu associated with it, 
returns the menu ID of the submenu in the markChar parameter. 


markChar The GetItemMark procedure returns the mark or the submenu of this 
item in the markChar parameter. A menu item can have a mark or a 
submenu attached to it, but not both. If this menu item has a marking 
character, the Get ItemMark procedure returns the mark. If this menu 
item has a submenu associated with it, the Get ItemMark procedure 
returns the menu ID of the submenu. If the item doesn’t have a mark or 
asubmenu, Get ItemMark returns 0 in this parameter. 


DESCRIPTION 


If the item has a mark or submenu, the Get ItemMark procedure returns the mark or the 
menu ID of the submenu of the specified menu item in the markChar parameter (or 0 if 
the item doesn’t have a mark or a submenu). 


SetItem Mark 


Use the Set ItemMark procedure to set the mark of a specific menu item or to change or 
set the submenu associated with a menu item. 





PROCEDURE SetItemMark (theMenu: MenuHandle; item: Integer; 
markChar: Char); 


theMenu A handle to the menu record of the menu containing the menu item 
whose mark or submenu you wish to set. 


item The item number of the menu item. The Set ItemMark procedure sets 
the mark or the submenu of this item. 


markChar The SetItemMark procedure sets the mark or submenu of this item 
according to the information in the markChar parameter. 
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To set the mark of a menu item, specify the marking character in the 
markChar parameter. You can also use one of these constants to specify 
that the item has no mark, has a checkmark as the marking character, or 
has the diamond symbol as the marking character: 


CONST 

noMark = 0; {no marking character} 
checkMark = $12; { checkmark } 
diamondMark = $13; {diamond symbol} 


To set the submenu associated with this menu item, specify the menu ID 
of the submenu in the markChar parameter. 


The Set ItemMark procedure sets the mark or the submenu of the specified menu item. 


See Listing 3-11 on page 3-61 for examples of setting the mark of a menu item. 


CheckItem 


DESCRIPTION 


SEE ALSO 
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Use the CheckItem procedure to set the mark of a specific menu item to a checkmark or 
to remove a mark from a menu item. 





PROCEDURE CheckItem (theMenu: MenuHandle; item: Integer; 


theMenu 


item 


checked 





checked: Boolean); 


A handle to the menu record of the menu containing the menu item 
whose mark you wish to set to a checkmark or whose mark you wish to 
remove. 


The item number of the menu item. 


The CheckItem procedure sets or removes the mark of the item 
according to the information in the checked parameter. 


To set the mark of a menu item to a checkmark, specify TRUE in the 
checked parameter. To remove a checkmark or any other mark from a 
menu item, specify FALSE in the checked parameter. 








The CheckItem procedure sets the mark of the specified menu item to a checkmark or 
removes any mark from the menu item. 


See Listing 3-11 on page 3-61 for examples of setting the mark of a menu item. 
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GetItemIcon 


Use the Get ItemIcon procedure to get the icon or script code of a specific menu item. If 
the menu item’s keyboard equivalent field contains $1C, the returned number represents 
the script code of the menu item. Otherwise, the returned number represents the item’s 
icon number. 


PROCEDURE GetItemIcon (theMenu: MenuHandle; item: Integer; 
VAR iconIndex: Byte); 





theMenu A handle to the menu record of the menu containing the menu item 
whose icon or script code you wish to get. 


item The item number of the menu item. The Get ItemIcon procedure returns 
the icon number or script code of this item. 


iconIndex For menu items that do not specify $1C in the keyboard equivalent field, 
the Get ItemIcon procedure returns the icon number of the item’s icon 
in this parameter. The icon number returned in this parameter is a value 
from 1 through 255 if the menu item has an icon associated with it and is 
0 otherwise. You can add 256 to the icon number to generate the resource 
ID of the 'cicn', 'ICON', or 'SICN' resource that describes the icon of 
the menu item. For example, if the Get ItemIcon procedure returns 5 in 
this parameter, then the icon of the menu item is described by an icon 
resource with resource ID 261. 
For menu items that contain $1C in the keyboard equivalent field, the 
Get ItemIcon procedure returns the script code of the menu item. The 
Menu Manager displays the menu item using this script code if the 
corresponding script system is installed. 


DESCRIPTION 


The Get ItemIcon procedure returns the icon number or script code of the specified 
menu item in the iconIndex parameter (or 0 if the item doesn’t have an icon or a 
script code). 


SetItemIcon 


Use the Set ItemIcon procedure to set the icon number or script code of a specific 

menu item. Usually you display menu items in the current system script; however, if 
needed, you can use the Set ItemIcon procedure to set the script code of a menu item. 
For an item’s script code to be set, the keyboard equivalent field of the item must contain 
$1C. If the keyboard equivalent field contains any other value, the Set ItemIcon 
procedure interprets the specified number as the item’s icon number. 





PROCEDURE SetItemIcon (theMenu: MenuHandle; item: Integer; 
iconIndex: Byte); 
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theMenu 


item 


iconIndex 


A handle to the menu record of the menu containing the menu item 
whose icon (or script code) you wish to set. 


The item number of the menu item. The Set ItemIcon procedure sets 
the icon (or script code) of this item. 


If the menu item’s keyboard equivalent field does not contain $1C, the 
Set ItemIcon procedure sets the icon number of the item’s icon to the 
number defined in this parameter. The icon number you specify should 
be a value from 1 through 255 (or from 1 through 254 if the item has a 
small or reduced icon) or 0 if the item does not have an icon. 


The Menu Manager adds 256 to the icon number to generate the resource 
ID of the 'cicn' or 'ICON' resource that describes the icon of the menu 
item. For example, if you specify 5 as the value of the iconIndex 
parameter, when the Menu Manager needs to draw the item, it looks for 
an icon resource with resource ID 261. 


If the menu item’s keyboard equivalent field contains $1C, the 

Set ItemIcon procedure sets the script code of the menu item to the 
number defined in the iconIndex parameter. The Menu Manager 
displays the menu item using the specified script code if the 
corresponding script system is installed. 


You can specify 0 in the iconIndex parameter to indicate that the item 
uses the current system script and does not have an icon number. 


The Set ItemIcon procedure sets the icon number or script code of the specified menu 
item to the value in the iconIndex parameter. 


See “Changing the Icon or Script Code of Menu Items” beginning on page 3-62 for 
examples of setting the icon of a menu item. 


GetItemCmd 
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Use the Get It emCmd procedure to get the value of the keyboard equivalent field of a 


menu item. 


PROCEDURE GetItemCmd (theMenu: MenuHandle; item: Integer; 





theMenu 


item 


VAR cmdChar: Char); 


A handle to the menu record of the menu containing the menu item 
whose keyboard equivalent field you wish to get. 


The item number of the menu item. The Get ItemCmd procedure returns 
the keyboard equivalent field of this item. 
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cmdChar The value of the item’s keyboard equivalent field. The Menu Manager 
uses this value to map keyboard equivalents to menu commands or to 
indicate special characteristics of the menu item. 


If the cmdChar parameter contains $1B, the menu item has a submenu; a 
value of $1C indicates that the item has a script code; a value of $1D 
indicates that the Menu Manager reduces the item’s ' ICON" resource; 
and a value of $1E indicates that the item has an 'SICN' resource. 





DESCRIPTION 
The Get ItemCmd procedure returns the value in the keyboard equivalent field of the 
specified menu item in the cmdChar parameter (or 0 if the item doesn’t have a keyboard 
equivalent, submenu, script code, reduced icon, or small icon). 
SetItemCmd 
Use the Set ItemCmd procedure to set the value of the keyboard equivalent field of a 
menu item. You usually define the keyboard equivalents and other characteristics of 
your menu items in 'MENU' resources rather than using the Set ItemCmd procedure. 
PROCEDURE SetItemCmd (theMenu: MenuHandle; item: Integer; 
emdChar: Char); 
theMenu A handle to the menu record of the menu containing the menu item 
whose keyboard equivalent field you wish to set. 
item The item number of the menu item. The Set ItemCmd procedure sets the 
keyboard equivalent field of this item to the value specified in the 
cmdChar parameter. 
cmdChar The value of the item’s keyboard equivalent field. The Menu Manager 
uses this value to map keyboard equivalents to menu commands or to 
define special characteristics of the menu item. 
To indicate that the menu item has a submenu, specify $1B in the 
cmdChar parameter; specify a value of $1C to indicate that the item has a 
script code; specify a value of $1D to indicate that the Menu Manager 
should reduce the item’s 'ICON' resource to the size of a small icon; and 
specify a value of $1E to indicate that the item has an 'SICN' resource. 
The values $01 through $1A, as well as $1F and $20, are reserved for use 
by Apple. You should not use any of these reserved values in the 
cmdChar parameter. 
DESCRIPTION 


The Set ItemCmd procedure sets the value in the keyboard equivalent field of the 
specified menu item in the cmdChar parameter (you can specify 0 if the item doesn’t 
have a keyboard equivalent, submenu, script code, reduced icon, or small icon). If you 
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specify that the item has a submenu, you should provide the menu ID of the submenu as 
the item’s marking character. If you specify that the item has a script code, provide the 
script code in the icon field of the menu item. If you specify that the item has an 'SICN' 
or a reduced' ICON" resource, provide the icon number in the icon field of the item. 


Disposing of Menus 


If you no longer need a menu in the menu list, you can delete the menu using 
DeleteMenu. You should then release the memory associated with that menu using 
the DisposeMenu procedure if you created the menu using NewMenu; otherwise, 
use the Resource Manager procedure ReleaseResource. See the chapter “Resource 
Manager” in Inside Macintosh: More Macintosh Toolbox for information on the 
ReleaseResource routine. 








DisposeMenu 


DESCRIPTION 


SEE ALSO 


To release the memory occupied by a menu’s associated data structures, use either the 
DisposeMenu procedure or the Resource Manager procedure ReleaseResource. 
Use DisposeMenu if you created the menu using NewMenu; use ReleaseResource if 
you created the menu using GetMenu or read the resource in using Get NewMBar. 





You should delete the menu from the current menu list using Delet eMenu or 
ClearMenuBar before calling the DisposeMenu procedure. 


PROCEDURE DisposeMenu (theMenu: MenuHandle) ; 





theMenu A handle to the menu record of the menu you wish to dispose of. 


The DisposeMenu procedure releases the memory occupied by the specified menu’s 
menu record. The handle that you pass in the parameter theMenu is not valid after 
DisposeMenu returns. 


To delete a menu from the current menu list, see the description of the DeleteMenu 
procedure on page 3-109. 


Counting the Items ina Menu 
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If your application needs to count the number of items in a menu—for example, in a 
menu that can contain a variable number of menu items such as the Font menu or Help 
menu—use the CountMItems function. 
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CountMItems 


DESCRIPTION 


You can count the number of items in a menu using the CountMItems function. 
FUNCTION CountMItems (theMenu: MenuHandle): Integer; 


theMenu A handle to the menu record of the menu whose items your application 
needs to count. 


The CountMItems function counts the number of items in the specified menu and 
returns as its function result the number of items in the menu. 


Highlighting the Menu Bar 


You can highlight (invert) a menu title or the entire menu bar using the FlashMenuBar 
procedure. (The HiliteMenu procedure highlights only menu titles.) In most cases 
your application should not highlight the menu bar; use HiliteMenu to highlight a 
menu title. 


The user sets the number of times an enabled menu item flashes using the General 
Controls panel. The SetMenuF lash procedure can be used to control the number of 
times that menu items blink when the user chooses an enabled menu item; usually you 
should not change the setting chosen by the user. 


FlashMenuBar 


DESCRIPTION 





Use the FlashMenuBar procedure to highlight (invert) a menu title or the entire menu 
bar. You can call FlashMenuBar twice in a row to make the menu bar blink. 





PROCEDURE FlashMenuBar (menuID: Integer); 














menuID The menu ID of the menu whose title you want to invert. Use 0 in this 
parameter to invert the entire menu bar. If the specified menu ID does not 
exist in the current menu list, the FlashMenuBar procedure inverts the 
entire menu bar. 


The FlashMenuBar procedure inverts the title of the specified menu or inverts the 
menu bar. To prevent unexpected colors from appearing in the menu bar, you should 
not call FlashMenuBar to invert a menu title while the entire menu bar is inverted. 
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Only one menu title can be inverted at a time. If no menus are currently highlighted, 
calling FlashMenuBar with a specific menu ID inverts the title of that menu. If you call 
FlashMenuBar again specifying another menu ID that is different from that of the 
previously inverted menu title, FlashMenuBar restores the previously highlighted 
menu to normal and then inverts the title of the specified menu. 





You can also highlight a menu using the HiliteMenu procedure, described on 
page 3-119. 


SetMenuFlash 


DESCRIPTION 


Use the SetMenuF lash procedure to set the number of times a menu item blinks when 
the user chooses an enabled menu item. The user sets this value using the General 
Controls panel, and in most cases your application should not change the value set by 
the user. 


PROCEDURE SetMenuFlash (count: Integer); 


count The number of times an enabled menu item should blink when the user 
chooses it. This value is initially set to 3 by the General Controls panel. A 
count of 0 disables the blinking. Values greater than 3 can be slow and 
distracting to the user. 


The SetMenuF lash procedure sets the number of times that the Menu Manager causes 
a menu item to blink when the user chooses an enabled menu item. 


The appearance of blinking in a menu item is determined by the menu’s menu definition 
procedure. 


ASSEMBLY-LANGUAGE INFORMATION 


The global variable MenuF lash contains the current count (number of times) a menu 
item blinks when chosen by the user. 


Recalculating Menu Dimensions 
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The Menu Manager uses the CalcMenuSize procedure to recalculate the dimensions of 
a menu whenever its contents have changed. In most cases your application does not 
need to use the CalcMenuSize procedure. 
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CalcMenuSize 


The CalcMenuSize procedure recalculates the horizontal and vertical dimensions of 
a menu and stores the new values in the menuWidth andmenuHeight fields of the 
menu record. 








PROCEDURE CalcMenuSize (theMenu: MenuHandle) ; 


theMenu A handle to the menu record of the menu whose dimensions need 
recalculating. 


DESCRIPTION 


The CalcMenuSize procedure uses the menu definition procedure of the specified 
menu to calculate the dimensions of the menu. 


Managing Entries in the Menu Color Information Table 


The Menu Manager maintains color information about an application’s menus in a menu 
color information table. The standard menu definition procedure defines the standard 
color for the menu bar, titles of menus, text and characteristics of a menu item, and 
background color of a displayed menu. You can change any of these colors by adding 
entries to your application’s menu color information table. However, note that in most 
cases your application should use the default colors for its menus. 


You can provide an 'mctb' resource with resource ID 0 as one of your application’s 
resources if you want to use colors other than the default colors for your application’s 
menu bar and menus. (Or you can provide an 'mctb' resource with the same resource 
ID as a 'MENU' resource to define the color entries for a single menu.) You can also add 
entries to or delete entries from your application’s menu color information table using 
the SetMCEntries andDeleteMCEnt ries procedures. You can get information about 
an entry using the GetMCEnt ry function. To get or set your application’s menu color 
information table, use the GetMCInfo function or SetMCInfo procedure. To dispose of 
your application’s menu color information table, use the DisposeMCInfo procedure. 














Note that the menu color information table uses a format that is different from the 
standard color table format. “The Menu Color Information Table Record” beginning on 
page 3-98 describes the format of the menu color information table in detail. 


GetMCInfo 


Use the GetMCInfo function to get a handle to a copy of your application’s menu color 
information table. 


FUNCTION GetMCInfo: MCTableHandle; 
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The GetMCInfo function creates a copy of your application’s menu color information 
table and returns a handle to the copy. If the copy fails, GetMCInfo returns NIL. 


See “The Menu Color Information Table Record” beginning on page 3-98 for a 
description of the format of the menu color information table. 


Use the SetMCInfo procedure to set your application’s menu color information table. 


PROCEDURE SetMCInfo (menuCTbl: MCTableHandle); 





menuCTbl A handle to a menu color information table. 


The SetMCInfo procedure copies the table specified by the menuCTb1 parameter 
to your application’s menu color information table. If successful, the SetMCInfo 
procedure is responsible for disposing of your application’s current menu color 
information table, so your application does not need to explicitly dispose of the 
current table. 


Your application should call the Memory Manager function MemError to determine 
whether the SetMCInfo procedure successfully copied the table. If the SetMCInfo 
procedure cannot successfully copy the table, it does not dispose of the current menu 
color information table and the MemError function returns a nonzero result code. If the 
SetMCInfo procedure is able to successfully copy the table, it disposes of the current 
menu color information table and the MemError function returns the noErr result code. 


If the menu color information table specifies a new menu bar color or new menu title 
colors, your application should call DrawMenuBar after calling SetMCInfo. 


Note that Get NewMBar does not save your application’s current menu color information 
table. If your application changes menu bars, you can save and restore your application’s 
current menu color information table by calling GetMCInfo before Get NewMBar and 
calling SetMCInfo afterward. 





See “The Menu Color Information Table Record” beginning on page 3-98 for a 
description of the format of the menu color information table. For an example of using 
the GetMCInfo and SetMCInfo routines to save and restore menu color information, 
see Listing 3-6 on page 3-52. See Inside Macintosh: Memory for information on the 
MemError function 
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DisposeMCInfo 


DESCRIPTION 


Use the DisposeMCInfo procedure to dispose of a menu color information table. The 
DisposeMCInfo procedure is also available as the DispMCInfo procedure. 


PROCEDURE DisposeMCInfo (menuCTbl: MCTableHandle) ; 


menuCTbl A handle to a menu color information table. 


The DisposeMCInfo procedure disposes of the menu color information table referred 
to by the menuCTb1 parameter. 


GetMCEntry 


DESCRIPTION 





Use the GetMCEnt ry function to return information about an entry in your application’s 
menu color information table. You can get information about the menu bar entry, a menu 
title entry, or a menu item entry. 





FUNCTION GetMCEntry (menuID: Integer; menuItem: Integer) 
MCEntryPtr; 








menulD The menu ID that the GetMCEnt ry function should use to return 
information about the menu color information table. Specify 0 in the 
menuID parameter (and the menuItem parameter) to get the menu bar 
entry. Specify the menu ID of a menu in the current menu list in the 
menuID parameter and 0 in the menuItem parameter to get a specific 
menu title entry. Specify the menu ID of a menu in the current menu list 
in the menuID parameter and an item number in themenuItem 
parameter to get a specific menu item entry. 





menultem The menu item that the GetMCEntry function should use to return 
information about the menu color information table. If you specify 0 in 
this parameter, GetMCEnt ry returns either the menu bar entry or the 
menu title entry, depending on the value of the menuID parameter. If you 
specify the item number of a menu item in this parameter and the menu 
ID of a menu in the current menu list in the menuID parameter, 
GetMCEnt ry returns a specific menu item entry. 








The GetMCEnt ry function returns a menu bar entry, a menu title entry, or a menu item 
entry according to the values specified in the menuID andmenuItem parameters. If 
the GetMCEnt ry function finds the specified entry in your application’s menu color 
information table, it returns a pointer to a record of data type MCEnt ry. If the specified 
entry is not found, GetMCEnt ry returns NIL. 
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WARNING 

The menu color information table is relocatable, so the pointer returned 
by the GetMCEnt ry function may not be valid across routines that may 
move or purge memory. Your application should make a copy of the 
menu color entry record if necessary. & 





“The Menu Color Information Table Record” beginning on page 3-98 describes the 
entries in a menu color information table. 


SetMCEntries 


DESCRIPTION 


Use the SetMCEnt ries procedure to set entries in your application’s menu color 
information table. You can set any or all of your application’s menu item entries and 
menu title entries or the menu bar entry. 








PROCEDURE SetMCEntries (numEntries: Integer; 
menuCEntries: MCTablePtr); 

















numEntries The number of entries contained in the array of menu color entry records. 


menuCEntries 
A pointer to an array of menu color entry records. Specify the number of 
records in the array in the numEnt ries parameter. 





The SetMCEnt ries procedure sets any specified menu bar entry, menu title entry, or 
menu item entry according to the values specified in the menu color entry records. If 
an entry already exists for a specified menu color entry, the SetMCEnt ries procedure 
updates the entry in your application’s menu color information table with the new 
values. If the entry doesn’t exist, it is added to your application’s menu color 
information table. 





If any of the added entries specify a new menu bar color or new menu title colors, your 
application should call DrawMenuBar to update the menu bar with the new colors. 


SPECIAL CONSIDERATIONS 
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The SetMCEnt ries procedure may move or purge memory. Your application should 
make sure that the array specified by the menuCEnt ries parameter is nonrelocatable 
before calling SetMCEntries. 
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“The Menu Color Information Table Record” beginning on page 3-98 describes the 
entries in a menu color information table. 


DeleteMCEntries 


Use the DeleteMCEnt ries procedure to delete one or all entries for a specific menu 
from your application’s menu color information table. You can delete a menu item entry, 
a menu title entry, the menu bar entry, or all menu item entries of a specific menu. The 
DeleteMCEnt ries procedure is also available as the De1MCEnt ries procedure. 














PROCEDURE DeleteMCEntries (menuID: Integer; menuItem: Integer); 





menuID The menu ID that the DeleteMCEnt ries procedure should use to 
determine which entry to delete from the menu color information table. 
Specify 0 in the menuID parameter (and the menuItem parameter) to 
delete the menu bar entry. Specify the menu ID of a menu in the current 
menu list in the menuID parameter and 0 in the menuItem parameter to 
delete a specific menu title entry. Specify the menu ID of a menu in the 
current menu list in the menuID parameter and an item number in the 
menulItem parameter to delete a specific menu item entry. 





menuItem The menu item that the DeleteMCEntries procedure should use to 
determine which entry to delete from the menu color information table. If 
you specify 0 in this parameter, DeleteMCEnt ries deletes either the 
menu bar entry or menu title entry, depending on the value of the 
menuID parameter. If you specify the item number of a menu item in this 
parameter and the menu ID of a menu in the current menu list in the 
menuID parameter, DeleteMCEnt ries deletes a specific menu item 
entry. You can also delete all menu item entries for a specific menu from 
your application’s menu color information table using this constant: 


CONST 
mctAllItems = —98; {delete all menu item entries } 
{ for the specified menu} 








DESCRIPTION 
The DeleteMCEnt ries procedure deletes a menu bar entry, a menu title entry, a menu 
item entry, or all menu item entries of a given menu, according to the values specified in 
the menuID andmenuItem parameters. If the GetMCEnt ry function does not find the 
specified entry in your application’s menu color information table, it does not delete the 
entry. Your application should not delete the last entry in your application’s menu color 
information table. 








If any of the deleted entries changes the menu bar color or a menu title color, your 
application should call DrawMenuBar to update the menu bar. 
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Application-Defined Routine 


Apple provides a standard menu definition procedure and standard menu bar definition 
function. The Menu Manager uses the menu definition procedure and menu bar 
definition function to display and perform basic operations on menus and the menu bar. 
Although the Menu Manager allows you to provide your own menu bar definition 
function, Apple recommends that you use the standard menu bar definition function. 
Similarly, in most cases the standard menu definition procedure should meet the needs 
of most applications. However, if your application has special needs, you can choose to 
provide your own menu definition procedure. If you do so, define your menu definition 
procedure so that it emulates the standard behavior of menus as much as possible. If you 
define your own menus, they should follow the guidelines described in this chapter and 
in Macintosh Human Interface Guidelines. 


The Menu Definition Procedure 


The Menu Manager uses the menu definition procedure of a menu to draw the menu 
items in the menu, to determine which item the user chose from the menu, and to 
calculate the menu’s dimensions. If you provide your own menu definition procedure, 
it should also perform these tasks. 


Apple provides a standard menu definition procedure, stored as a resource in the System 
file. The standard menu definition procedure is the 'MDEF' resource with resource ID 0. 
When you define your menus, you specify the menu definition procedure the Menu 
Manager should use when managing them. You'll usually want to use the standard 
menu definition procedure for your application. However, if you need a feature not 
provided by the standard menu definition procedure (for example, if you want to 
include more graphics in your menus), you can choose to write your own menu 
definition procedure. 





MyMenuDef 
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You can provide your own menu definition procedure if you need special features in a 
menu other than those provided by the standard menu definition procedure. This section 
describes how to define your own menu definition procedure, defines the parameters 
passed to your procedure by the Menu Manager, and describes the general actions your 
procedure should perform. 


PROCEDURE MyMenuDef (message: Integer; theMenu: MenuHandle; 
VAR menuRect: Rect; hitPt: Point; 
VAR whichItem: Integer); 





message A number that identifies the operation that the menu definition proce- 
dure should perform. The message parameter can contain any one of 
these values: 


Menu Manager Reference 


CHAPTER 3 


Menu Manager 


theMenu 


menuRect 


hitPt 


whichItem 


CONST 
mDrawMsg = 0; {draw the menu} 
mChooseMsg = 1; {tell which item was chosen } 
{ and highlight it} 
mSizeMsg = 2; {calculate menu dimensions} 
mPopUpMsg = 3; {calculate rectangle of } 


{ the pop-up box} 


Your menu definition procedure should not respond to any value other 
than the four constants listed above. 


A handle to the menu record of the menu that the operation should affect. 


The rectangle (in global coordinates) in which the menu is located; the 
Menu Manager provides this information to the menu definition 
procedure only when the value in the message parameter is the 
mDrawMsg ormChooseMsg constant. 


When the value in the message parameter is the mPopUpMsg constant, 
the menu definition procedure should calculate and then return the 
dimensions of the pop-up box in this parameter. When the value in the 
message parameter is the mSizeMsg constant, the menu definition 
procedure should calculate the horizontal and vertical dimensions of the 
menu rectangle and store these values in the menuWidth and 
menuHeight fields of the menu record. 


A mouse location (in global coordinates). The Menu Manager provides 
information in this parameter to the menu definition procedure when the 
value in the message parameter is the mchooseMsg or mPopUpMsg 
constant. When the menu definition procedure receives the mchooseMsg 
constant in the message parameter, it should determine whether the 
mouse location specified in the hit Pt parameter is in an enabled menu 
item and highlight or unhighlight the item specified in the whichItem 
parameter appropriately. When the menu definition procedure receives 
the mPopUpMsg constant in the message parameter, the hitPt 
parameter contains the top-left coordinates of the closed pop-up box, 
which your procedure can use to calculate the rectangle of the open 
pop-up box. 

The item number of the last item chosen from this menu (or 0 if an item 
hasn’t been chosen). The Menu Manager provides information in this 
parameter to the menu definition procedure when the value in the 
message parameter is the mchooseMsg constant. When the menu 
definition procedure receives the mchooseMsg constant in the 

message parameter, it should determine whether the mouse location 
specified in the hitPt parameter is in an enabled menu item. If so, the 
menu definition procedure should unhighlight the item specified by 

the whichItem parameter, highlight the new item, and return the new 
item number in whichItem. If the mouse location isn’t in an enabled 
menu item, the menu definition procedure should unhighlight the 

item specified by the whichItem parameter and return 0 in the 
whichItem parameter. 
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The Menu Manager calls your menu definition procedure whenever it needs your 
definition procedure to perform a certain action on a specific menu. The action 
your menu definition procedure should perform depends on the value of the 
message parameter. 


If you provide your own menu definition procedure, store it in a resource of type 
"MDEF'' and include its resource ID in the description of each menu that uses your own 
definition procedure. If you create a menu using GetMenu (or Get NewMBar), the Menu 
Manager reads the menu definition procedure into memory and stores a handle to it in 
the menuProc field of the menu’s menu record. 








If you create a menu using NewMenu, the Menu Manager stores a handle to the standard 
menu definition procedure in the menuP roc field of the menu’s menu record. In this 

case you must replace the value in the menuProc field with a handle to your own 
procedure and then call the CalcMenuSize procedure. If your menu definition 
procedure is in a resource file, you can get its handle by using the Resource Manager to 
read it from the resource file into memory. However, note that you should usually store 
your menus in resources (rather than using NewMenu) to make your application easier to 
localize. See the “Resource Manager” chapter in Inside Macintosh: More Macintosh Toolbox 
for information on the Resource Manager. 


The menu definition procedure is responsible for drawing the contents of the menu and 
its menu items, determining whether the cursor is in a displayed menu, highlighting and 
unhighlighting menu items, and calculating a menu’s dimensions. 


When the Menu Manager requests your menu definition procedure to perform an action 
on a menu, it provides your procedure with a handle to its menu record. This allows 
your procedure to access the data in the menu record and to use any data in the variable 
data portion of the menu record to appropriately handle the menu items. 


When the Menu Manager creates a menu as a result of an application calling GetMenu 
or GetNewMBar, it fills out the menuID, menuProc, enableFlags, menuTitle, and 
itemDefinitions fields of the menu record according to its resource definition. If the 
menu is managed by your menu definition procedure, the Menu Manager calls your 
procedure (specifying mSizeMsg) to calculate and fill in the menuHeight and 
menuWidth fields of the menu record. The menu items are described by a variable 
length field (itemDefinitions) in the menu record. Your menu definition procedure 
can define and use this variable-length data in any manner it chooses. 


For pop-up menus that are not implemented as controls, the Menu Manager uses the 
menu definition procedure to support pop-up menus. If your menu definition procedure 
supports pop-up menus, it should respond appropriately to the mPopUpMsg constant. 


The Menu Manager specifies the mPopUpMsg constant in the message parameter and 
calls your menu definition procedure whenever it needs to calculate the rectangle 
bounded by the pop-up box for a pop-up menu that is managed by your menu 
definition procedure. The parameter theMenu contains a handle to the menu record 

of the pop-up menu, the hit Pt parameter contains the top-left coordinates of the pop- 
up box, and whichItem contains the previously chosen item. Your menu definition 
procedure should calculate the rectangle in which the pop-up menu is to appear 
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and return this rectangle in the menuRect parameter. If the menu is so large that it 
scrolls, return the actual top of the menu in the whichItem parameter. For pop-up 
menus, your menu definition procedure also must place the pop-up menu’s scrolling 
information in the global variables TopMenuItem and AtMenuBottom. Place in 
TopMenultenm the pixel value of the top of the scrollable menu, and place in 
AtMenuBottom the pixel value of the bottom of the scrollable menu. 


Note 

Your menu definition procedure should not assume that the A5 
register is properly set up, so your procedure can’t refer to any of 
the QuickDraw global variables. 


SEE ALSO 
For additional information on how your menu definition procedure should respond 
when it receives the mDrawMsg, mChooseMsg, ormSizeMsg constant in the message 
parameter, see “Writing Your Own Menu Definition Procedure” beginning on page 3-87. 
Resources 








This section describes the menu ('MENU') resource, menu bar ('MBAR') resource, and 
menu color information table ('mctb') resource. Usually you should define your menus 
using 'MENU' resources, define the menus in your menu bar in an 'MBAR" resource, and 
use the Get NewMBar function to read in the descriptions of your menus and menu bar. 





If you want to use colors other than the default colors in a menu, you can provide an 
"mctb' resource with the same resource ID as its corresponding 'MENU' resource, or 
you can provide an 'mctb' resource with resource ID 0 to define colors for all your 
menus and your menu bar. 





If you choose to provide your own menu definition procedure, you should store your 
routine in an 'MDEF' resource. 








To create a 'MENU', an 'MBAR', or an 'mctb' resource, either you can specify the 
resource description in an input file and compile the resource using a resoure compiler, 
such as Rez, or you can directly create your resources in a resource file using a tool such 
as ResEdit. This section describes the structures of these resources after they are 
compiled by the Rez resource compiler. If you are interested in creating the Rez input 
files for these resources, see “Using the Menu Manager,” beginning on page 3-41, for 
detailed information. 


The Menu Resource 





You can provide descriptions of your menus in 'MENU' resources and use the GetMenu 
function or Get NewMBar function (if you also provide an 'MBAR' resource) to read in 
the descriptions of your menus. After reading in the resource description, the Menu 
Manager stores the information about specific menus in menu records. 
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WARNING 
Menus in a resource must not be purgeable. A 





Figure 3-37 shows the format of a compiled 'MENU' resource. See Listing 3-1 on 
page 3-43 for a description of a 'MENU' resource in Rez input format. 








Figure 3-37 Structure of a compiled menu ("MENU") resource 
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A compiled version of a 'MENU' resource contains the following elements: 


Menu ID. Each menu in your application should have a unique menu ID. Note that 
the menu ID does not have to match the resource ID, although by convention most 
applications assign the same number for a menu’s resource ID and menu ID. A 
negative menu ID indicates a menu belonging to a desk accessory (except for 
submenus of a desk accessory). A menu ID from 1 through 235 indicates a menu (or 
submenu) of an application; a menu ID from 236 through 255 indicates a submenu of 
a desk accessory. Apple reserves the menu ID of 0. 


Placeholder (two integers containing 0) for the menu’s width and height. After 
reading in the resource data, the Menu Manager requests the menu’s menu definition 
procedure to calculate the width and height of the menu and to store these values in 
the menuWidth andmenuHeight fields of the menu record. 


Resource ID of the menu’s menu definition procedure. If the integer 0 appears here (as 
specified by the textMenuProc constant in the Rez input file), the Menu Manager 
uses the standard menu definition procedure to manage the menu. If you provide 
your own menu definition procedure, its resource ID should appear in these bytes. 
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After reading in the menu’s resource data, the Menu Manager reads in the menu 
definition procedure, if necessary. The Menu Manager stores a handle to the menu’s 
menu definition procedure in the menuP roc field of the menu record. 


m Placeholder (an integer containing 0). 


m The initial enabled state of the menu and first 31 menu items. This is a 32-bit value, 
where bits 1-31 indicate if the corresponding menu item is disabled or enabled, and 
bit 0 indicates whether the menu is enabled or disabled. The Menu Manager 
automatically enables menu items greater than 31 when a menu is created. 


m The length (in bytes) of the menu title. 
m The title of the menu. 


m Variable-length data that describes the menu items. If you provide your own menu 
definition procedure, you can define and provide this variable-length data according 
to the needs of your procedure. The Menu Manager simply reads in the data for each 
menu item and stores it as variable data at the end of the menu record. The menu 
definition procedure is responsible for interpreting the contents of the data. For 
example, the standard menu definition procedure interprets this data according to the 
description given in the following paragraphs. 


m Placeholder (a byte containing 0) to indicate the end of the menu item definitions. 





If you use the standard menu definition procedure, your 'MENU' resource should 

describe the menu items in this manner. For each menu item, you need to provide its 
text, the icon number, the keyboard equivalent or other value ($1B to indicate the menu 
item has a submenu, $1C to indicate a script code other than the system script for the 
item’s text, $1D to indicate the item’s icon should be reduced, or $1E to indicate that an 
"SICN' icon should be used), the marking character of the menu item or menu ID of the 
menu item’s submenu, and the font style of the menu item’s text. If an item doesn’t have 
a particular characteristic, specify 0 for that characteristic. Figure 3-38 shows the 
variable-length data portion of a compiled 'MENU' resource that uses the standard menu 
definition procedure. 





Figure 3-38 The variable-length data that describes menu items as defined by the standard 
menu definition procedure 
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The variable-length data portion of a compiled version of a 'MI 


ENU' resource that uses 





the standard menu definition procedure contains the following elements: 


m Length (in bytes) of the menu item’s text. 


m Text of the menu item. 


a Icon number, script code, or 0 (as specified by the noicon constant in a Rez input file) 


if the menu item doesn’t contain an icon and uses the system script. The icon number 
is anumber from 1 through 255 (or from 1 through 254 for small or reduced icons). 
The Menu Manager adds 256 to the icon number to generate the resource ID of the 
menu item’s icon. If a menu item has an icon, you should also provide a 'cicn' oran 
"ICON' resource with the resource ID equal to the icon number plus 256. If you want 
the Menu Manager to reduce an 'ICON' resource to the size of a small icon, also 
provide the value $1D in the keyboard equivalent field. If you provide an 'SICN' 
resource, provide $1E in the keyboard equivalent field. Otherwise, the Menu Manager 
looks first fora 'cicn' resource with the calculated resource ID and uses that icon. If 
you want the Menu Manager to draw the item’s text in a script other than the system 
script, specify the script code here and also provide $1C in the keyboard equivalent 
field. If the script system for the specified script is installed, the Menu Manager draws 
the item’s text using that script. An item that is drawn in a script other than the 
system script cannot also have an icon. 


Keyboard equivalent (specified as a 1-byte character), the value $1B (as specified by 
the constant hierarchicalMenu ina Rez input file) if the item has a submenu, the 
value $1C if the item uses a script other than the system script, or 0 (as specified by 
the nokey constant in a Rez input file) if the item has neither a keyboard equivalent 
nor a submenu and uses the system script. A menu item can have a keyboard 
equivalent, a submenu, a small icon, a reduced icon, or a script code, but not more 
than one of these characteristics. For items containing icons, you can provide $1D in 
this field if you want the Menu Manager to reduce an 'ICON' resource to the size 

of a small icon. Provide $1E if you want the Menu Manager to use an 'SICN' 
resource for the item’s icon. The values $01 through $1A as well as $1F and $20 are 
reserved for use by Apple; your application should not use any of these reserved 
values in this field. 


Marking character, the menu ID of the item’s submenu, or 0 (as specified by the 
nomark constant in a Rez input file) if the item has neither a mark nor a submenu. A 
menu item can have a mark or a submenu, but not both. Submenus of an application 
should have menu IDs from 1 through 235; submenus of a desk accessory should have 
menu IDs from 236 through 255. 


Font style of the menu item. The constants bold, italic, plain, outline, and 
shadow can be used ina Rez input file to define their corresponding styles. 


If you provide your own menu definition procedure, you should use the same format 
for your resource descriptions of menus as shown in Figure 3-37. You can use the same 
format or a format of your choosing to describe menu items. You can also use bits 1-31 
of the enableFlags field of the menu record as you choose; however, bit 0 must still 
indicate whether the menu is enabled or disabled. 
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The Menu Bar Resource 


You can describe the order and number of menus in your menu bar in an 'MBAR' 
resource, and you can describe your menus in 'MENU' resources. If you do so, you can 
use the Get NewMBar function to read in the descriptions of your menus and create a 
new menu list. The Menu Manager stores information about your application’s menu 
bar in a menu list. Figure 3-39 shows the format of a compiled 'MBAR' resource. (See 
Listing 3-4 on page 3-49 for a description of an 'MBAR' resource in Rez input format.) 




















Figure 3-39 Structure of a compiled menu bar ('MBAR") resource 
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A compiled version of an 'MBAR"' resource contains the following elements: 
m= Number of menus described by this menu bar. 


m A variable number (the amount should match the number declared in the first 2 bytes) 
of resource IDs; each resource ID should identify a 'MENU' resource. 





If you use the Get NewMBar function, the Menu Manager places the menus in the menu 
bar according to the order that they appear in the 'MBAR' resource. 





The Menu Color Information Table Resource 


To use colors other than the default colors in a menu, provide a menu color information 
table ('mctb') resource with the same resource ID as its corresponding 'MENU' 
resource. You can also choose to provide an 'mctb' resource with resource ID 0 to 

define colors for all your menus and your menu bar. Note that you should usually use 
the default colors provided by the Menu Manager. 





The Menu Manager stores color information about your application’s menus and menu 
bar in a menu color information table. If you provide an 'mctb' resource with resource 
ID 0, the Menu Manager reads the resource in when your application calls InitMenus 
and stores the information in your application’s menu color information table. If you 

provide an 'mctb' resource with the same resource ID as a 'MENU' resource, when you 
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use Get Menu to read in the resource description of the menu (or Get NewMBar to read 
in all menus in the menu bar), the Menu Manager also reads in any associated 'mctb' 
resource (if it exists). “The Menu Color Information Table Record” beginning on 

page 3-98 describes the format of the menu color information table. 


Figure 3-40 shows the format of acompiled 'mctb' resource. 


Figure 3-40 Structure of a compiled menu color information table ('mctb') resource 





A compiled version of an 'mctb' resource contains the following elements: 
m acount of the number of menu color entry descriptions 
m a variable number of menu color entries 


A color entry defines colors for various parts of the menu and menu bar. Figure 3-41 on 
the next page shows the format of a compiled menu color entry in an 'mctb' resource. 


Each menu color entry in an 'mctb' resource contains the following: 


a A menu ID to indicate that this entry is either a menu item entry or menu title entry, 0 
to indicate that this entry is a menu bar entry, or —99 to indicate that this is the last 
entry in this resource. 


m An item number to indicate that this entry is a menu item entry, or 0 to indicate that 
this is either a menu title or menu bar entry. Together, the menu ID and menu item 
determine how the type of menu color entry is described. See Table 3-7 on page 3-100 
for a complete description of how the menu ID and menu item specifications define 
the type of menu color entry. 


m= RGB1: fora menu bar entry, the default color for menu titles; for a menu title entry, the 
title color of a specific menu; for a menu item entry, the mark color for a specific item. 


m= RGB2: for a menu bar entry, the default background color of a displayed menu; for a 
menu title entry, the default color for the menu bar; for a menu item entry, the color 
for the text of a specific item. 
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Figure 3-41 


Structure of a menu color entry inan 'mctb' resource 





m RGB3: fora 


menu bar entry, the default color of items in a displayed menu; for a 


menu title entry, the default color for items in a specific menu; for a menu item entry, 
the color for the keyboard equivalent of a specific item. 


m RGB4: fora 


menu bar entry, the default color of the menu bar; for a menu title entry, 


the background color of a specific menu; for a menu item entry, the background color 


of a specific 


menu. 


The Menu Definition Procedure Resource 


If you provide 


your own menu definition procedure, you should store it in a resource of 


type 'MDEF''. Provide as the resource data the compiled or assembled code of your 
menu definition procedure. The entry point of your procedure must be at the beginning 
of the resource data. 








If you define your menus in 'MENU' resources (and use the Get Menu or GetNewMBar 


function), you 
use to manage 





specify the menu definition procedure that the Menu Manager should 
the menu in the 'MENU' resource. If you use the NewMenu function 








(instead of 'MENU' resources), your application must explicitly replace the handle to 
the standard menu definition procedure in the menuProc field of the menu record with 
a handle to the desired menu definition procedure. 
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Summary of the Menu Manager 


Pascal Summary 


Constants 


CONST 


noMark = 0; {menu item doesn't have a marking character} 


{values for the message parameter to the menu definition procedure} 


mDrawMsg = 0; {draw the menu items of a menu} 


mChooseMsg 


ll 
hh 
~ 


{highlight or unhighlight a menu item as } 
{ appropriate if the cursor is in a menu item} 


mSizeMsg = 2; {calculate the dimensions of a menu} 
mPopUpMsg = 3; {calculate the open pop-up box rectangle} 
textMenuProc = 0; {resource ID of standard menu definition } 


{ procedure} 














hMenuCmd = 27; {constant ($1B) specified as keyboard equivalent } 
{ to indicate a menu item has a submenu} 
hierMenu = -1l; {constant used with InsertMenu routine to insert } 
{ a submenu or pop-up menu into the submenu } 
{ portion of the current menu list} 
mctAlliItems = —-98;{search for all items with the given ID} 
mctLastIDIndic = -99;{last menu color table entry has this value } 
{ in the ID field of the entry} 
Data Types 
TYPE 
MenulInfo = {menu record} 
RECORD 
menulID: Integer; {number that identifies the menu} 
menuWidth: Integer; {width (in pixels) of the menu} 
menuHeight: Integer; {height (in pixels) of the menu} 
menuProc: Handle; {menu definition procedure} 
enableFlags:LongInt; {indicates whether menu and } 
{ menu items are enabled} 
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menuData: Str255; 


{itemDefinitions} 











{title of menu} 
{variable-length data that } 


{ defines the menu items} 








END; 
MenuPtr = *“MenulInfo; {pointer to a menu record} 
MenuHandle = *MenuPtr; {handle to a menu record} 
MCEntry = {menu color entry record} 
RECORD 
mctID: Integer; {menu ID or 0 for menu bar} 
mctiItem: Integer; {menu item number or O for } 
{ menu title} 
mctRGB1: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctRGB2: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctRGB3: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctRGB4: RGBColor; {usage depends on mctID and } 
{ mctItem} 
mctReserved: Integer; {reserved} 
END; 
MCEntryPtr = *MCEntry; {pointer to a menu color entry record} 
MCTable = ARRAY[0..0] OF MCEntry; {menu color table} 
MCTablePtr = *MCTable; {pointer to a menu color table} 


MCTableHandle = *“MCTablePtr; {handle to a menu color table} 


Menu Manager Routines 


Initializing the Menu Manager 


PROCEDURE InitMenus; 














PROCEDURE InitProcMenu (resID: Integer); 


Creating Menus 


FUNCTION NewMenu (menuID: Integer; menuTitle: Str255) 
MenuHandle; 
FUNCTION GetMenu (resourceID: Integer): MenuHandle; 
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Adding Menus to and Removing Menus From the Current Menu List 


PROCEDURE InsertMenu 


PROCEDUR 


PROC 


= 
ay 








E DURE 





G 





DeleteMenu 





ClearMenuBar; 


(theMenu: MenuHandle; 


(menuID: Integer) ; 


Getting a Menu Bar Description From an 'MBAR' Resource 


FUNCTION GetNewMBar 


Getting and Setting the Menu Bar 


FUNCTION GetMenuBar: Handle; 


PROCEDURE SetMenuBar 


FUNCTION GetMBarHeight: 


Drawing the Menu Bar 


P 
P 


ROC 





ROC 








G 








EDURE DrawMenuBar; 
E DURE 





InvalMenuBar; 





(menuBarID: 


Integer): 


(menuList: Handle); 


Integer; 


Responding to the User’s Choice of a Menu Command 


FUNCTION MenuSelect 


FUNCTION MenukKey 


FUNCTION MenuChoice: LongInt; 
PROC 
FUNCTION PopUpMenuSelect 


PROC 
FUNCTION SystemEdit 








E DURE 


G 














EDURE 


G 








HiliteMenu 


SystemMenu 





(startPt: Point): 


(ch: Char): 


LongInt; 


(menuID: Integer) ; 


(menu: MenuHandle; 
Top: Integer; Left: Integer; 


PopUpItem: 


(menuResult: 


(editCmd: Integer): 


Getting a Handle to a Menu Record 


{some routines have two spellings, 


FUNCTION GetMenuHandle 


FUNCTION HMGetHelpMenuHandle 


Adding and Deleting Menu Items 


{some ro 


utines have two spellings, 


PROCEDURE AppendMenu 


PROCEDUR 
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InsertMenuItem 


(menuID: Integer): 


Integer): 
LongInt) ; 


(VAR mh: MenuHandle): 


(menu: MenuHandle; 


(theMenu: MenuHandle; 


afterItem: 
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Integer) ; 


beforeID: Integer); 


Handle; 


LongInt; 


LongInt; 


Boolean; 


see Table 3-8 for the alternate spelling} 





MenuHandle; 


OSErr; 








data: Str255); 


itemString: 


see Table 3-8 for the alternate spelling} 


Str255; 


PROCEDURE 
PROCEDURE 
PROCEDURE 
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DeleteMenuItem 
AppendResMenu 


InsertResMenu 


(theMenu: MenuH 
(theMenu: MenuH 
(theMenu: MenuH 
afterItem: Int 


Getting and Setting the Appearance of Menu Items 


{some routines have two spellings, 


PROCEDURE 
PROCEDURE 
PROCEDURE 





PROCEDURE 





PROCEDUR 


Gl 





PROCEDURE 


PROCEDURE 





PROCEDURE 


PROCEDURE 


PROCEDURE 


PROCEDURE 


PROCEDUR 


Gl 








PROCEDURE 


EnableItem 
DisableItem 
GetMenulItemText 


SetMenultemText 


GetItemStyle 


SetItemStyle 


GetItemMark 


SetItemMark 


CheckItem 


GetItemIcon 


SetItemIcon 


Get ItemCmd 


SetItemCmd 


Disposing of Menus 


PROCEDURE 


DisposeMenu 


Counting the Items in a Menu 


FUNCTION CountMItems 


Highlighting the Menu Bar 


PROCEDURE 
PROCEDURE 


FlashMenuBar 


SetMenuFlash 


(theMenu: MenuH 
(theMenu: MenuH 
(theMenu: MenuH 
VAR itemString: 
(theMenu: MenuH 
itemString: St 
(theMenu: MenuH 
VAR chStyle: S 
(theMenu: MenuH 
chStyle: Style 
(theMenu: MenuH 
VAR markChar: 

(theMenu: MenuH 
markChar: Char 
(theMenu: MenuH 
checked: Boole 
(theMenu: MenuH 
VAR iconIndex: 

(theMenu: MenuH 
iconIndex: Byt 
(theMenu: MenuH 
VAR cmdChar: C 
(theMenu: MenuH 
cmdChar: CHAR) 

(theMenu: MenuH 
(theMenu: MenuH 
(menuID: Intege 
(count: Integer 
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andle; item: Integer); 
andle; theType: ResType) ; 
andle; theType: ResType; 
eger); 





andle; item: Integer) ; 
andle; item: Integer); 
andle; item: Integer; 
Str255); 

andle; item: Integer; 
r255); 

andle; item: Integer; 
tyle); 

andle; item: Integer; 
\; 

andle; item: Integer; 
Char); 

andle; item: Integer; 
3 

andle; item: Integer; 
an); 

andle; item: Integer; 
Byte); 

andle; item: Integer; 

e); 

andle; item: Integer; 

HAR) ; 

andle; item: Integer; 
i 

andle); 

andle): Integer; 

Lr); 


i 


see Table 3-8 for the alternate spelling} 
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Recalculating Menu Dimensions 


PROCEDURE CalcMenuSize (theMenu: MenuHandle) ; 


Managing Entries in the Menu Color Information Table 


{some routines have two spellings, see Table 3-8 for the alternate spelling} 


FUNCTION GetMCInfo: MCTableHandle; 




















PROCEDURE SetMCInfo (menuCTbl: MCTableHandle) ; 

PROCEDURE DisposeMCInfo (menuCTbl: MCTableHandle) ; 

FUNCTION GetMCEntry (menuID: Integer; menuItem: Integer) 
MCEntryPtr; 

PROCEDURE SetMCEntries (numEntries: Integer; 














menuCEntries: MCTablePtr); 





PROCEDURE DeleteMCEntries (menuID: Integer; menulItem: Integer); 


Application-Defined Routine 





PROCEDURE MyMenuDef (message: Integer; theMenu: MenuHandle; 
VAR menuRect: Rect; hitPt: Point; 
VAR whichItem: Integer); 














C Summary 


Constants 


enum { 


#define noMark '\0' /*menu item doesn't have a marking character*/ 


/*values for the message parameter to the menu definition procedure*/ 


mDrawMsg = 0, /*draw the menu items of a menu*/ 
mChooseMsg = 1, /*highlight or unhighlight a menu item as */ 

/* appropriate if the cursor is in a menu item*/ 
mSizeMsg = 2, /*calculate the dimensions of a menu*/ 
mPopUpMsg = 3, /*calculate the open pop-up box rectangle*/ 
textMenuProc = 0, /*resource ID of standard menu definition */ 


/* procedure*/ 
hMenuCmd = 27, /*constant ($1B) specified as keyboard */ 
/* equivalent to indicate an item has a submenu*/ 





hierMenu = -1, /*constant used with InsertMenu to insert */ 
/* a submenu or pop-up menu into the submenu */ 
/* portion of the current menu list*/ 
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mctAllItems = -98,/*search for all items with the given ID*/ 
mctLastIDIndic = -99 /*last menu color table entry has this value */ 
/* in the ID field of the entry*/ 


hi 











Data Types 
struct MenulInfo { /*menu record*/ 
short menulD; /*number that identifies the menu*/ 
short menuWidth; /*width (in pixels) of the menu*/ 
short menuHeight; /*height (in pixels) of the menu*/ 
Handle menuProc; /*menu definition procedure*/ 
long enableFlags; /*indicates whether menu and */ 
/* menu items are enabled*/ 
Str255 menuData; /*title of menu*/ 
/*itemDefinitions*/ /*variable-length data that */ 
/* defines the menu items*/ 
}; 
typedef struct MenuInfo MenuInfo; /*pointer to a menu record*/ 
typedef MenuInfo *MenuPtr, **MenuHandle; /*handle to a menu record*/ 
struct MCEntry { /*menu color entry record*/ 
short mctID; /*menu ID or O for menu bar*/ 
short mctItem; /*menu item number or O for */ 
/* menu title*/ 
RGBColor mctRGB1; /*usage depends on mctID and */ 
/* mctItem*/ 
RGBColor mctRGB2; /*usage depends on mctID and */ 
/* mcetItem*/ 
RGBColor mctRGB3; /*usage depends on mctID and */ 
/* mcetItem*/ 
RGBColor mctRGB4; /*usage depends on mctID and */ 
/* mctItem*/ 
short mctReserved; /*reserved*/ 
}; 
typedef struct MCEntry MCEntry; 
typedef MCEntry *MCEntryPtr; /*pointer to a menu color entry record*/ 


/*menu color table*/ 
typedef MCEntry MCTable[1], *MCTablePtr, **MCTableHandle; 
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Menu Manager Routines 


Initializing the Menu Ma 


pascal void InitMenus 


3 


nager 


pascal void InitProcMenu 


Creating Menus 


pascal MenuHandle NewMenu 


pascal MenuHandle GetMenu 


(void) ; 


(short resID); 


(short menuID, const Str255 menuTitle); 


(short resourcelID) 


, 


Adding Menus to and Removing Menus From the Current Menu List 


pascal void InsertMen 


pascal void DeleteMenu 


u 





pascal void ClearMenu 


Bar 


(MenuHandle theMenu, 


(short menulID); 


(void) ; 


Getting a Menu Bar Description From an 'MBAR' Resource 


pascal Handle GetNewMBar 


Getting and Setting the Menu Bar 





pascal Handle GetMenu 





Bar 


pascal void SetMenuBar 





#define GetMBarHeight 


Drawing the Menu Bar 


Q) 


pascal void DrawMenuBar 





pascal void InvalMenu 


Bar 


(short menuBarID) ; 


(void) ; 


(Handle menulList) ; 


(* (short*) OxOBAA) 





(void) ; 


(void); 


Responding to the User’s Choice of a Menu Command 


pascal long MenuSelect 


pascal long MenuKey 


pascal long MenuChoice 


pascal void HiliteMenu 


pascal long PopUpMenuSelect 


(Point startPt); 
(short ch); 
(void) ; 

(short menulID); 


(MenuHandle menu, 





pascal void SystemMenu 





pascal Boolean System 


Edit 





short popUpItem) ; 
(long menuResult) ; 


(short editCmd) ; 
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Getting a Handle to a Menu Record 


{some routines have two spellings, 


pascal MenuHandle GetMenuHandle 


(short menulID); 


pascal OSErr HMGetHelpMenuHandle 


Adding and Deleting Menu Items 


{some routines have two spellings, 


pascal void AppendMenu 


void InsertMenuItem 


(MenuHandle *mh) ; 


(MenuHandle menu, 





pascal 


pascal void DeleteMenuItem 


pascal void AppendResMenu 


pascal void InsertResMenu 


(MenuHandle theMenu, 


see Table 3-8 for the alternate spelling} 





see Table 3-8 for the alternate spelling} 





ConstStr255Param itemString, 


short afterItem); 


(MenuHandle theMenu, 
(MenuHandle theMenu, 


(MenuHandle theMenu, 


short item); 


ResType theType) ; 





short afterItem); 


Getting and Setting the Appearance of Menu Items 


{some routines have two spellings, 


pascal void EnableItem 


pascal void DisableItem 


pascal void GetMenuItemText 


void SetMenuItemText 





pascal 


pascal void GetItemStyle 


pascal void SetItemStyle 


pascal void GetItemMark 


pascal void SetItemMark 


pascal void CheckItem 


pascal void GetItemIcon 


pascal void SetItemIcon 


Style *chStyle); 


short *markChar) ; 


short markChar) ; 
Boolean checked) ; 


short *iconIndex) ; 














short iconIndex); 
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(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 
Str255 itemString) ; 
(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 


(MenuHandle theMenu, 


ResType theType, 


ConstStr255Param data); 





for the alternate 


short item); 


short item); 


short item, 


short item, 


ConstStr255Param itemString) ; 


short item, 


short item, short 


short item, 


short item, 
short item, 
item, 


short 


short item, 


spelling} 


chStyle); 
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void GetItemCmd (MenuHandle theMenu, short item, short 
*cmdChar) ; 
void SetItemCmd (MenuHandle theMenu, short item, short cmdChar) ; 


Disposing of Menus 


pascal 


void DisposeMenu (MenuHandle theMenu) ; 


Counting the Items in a Menu 


pascal 


short CountMItems (MenuHandle theMenu) ; 


Highlighting the Menu Bar 


pascal 


pascal 


void FlashMenuBar (short menulID); 


void SetMenuFlash (short count); 


Recalculating Menu Dimensions 


pascal 


void CalcMenuSize (MenuHandle theMenu) ; 


Managing Entries in the Menu Color Information Table 


{some routines have two spellings, see Table 3-8 for the alternate spelling} 


pascal 
pascal 
pascal 
pascal 
pascal 


pascal 


MCTableHandle GetMCInfo (void) ; 
void SetMCInfo (MCTableHandle menuCTbl); 
void DisposeMCInfo (MCTableHandle menuCTbl) ; 








MCEntryPtr GetMCEntry (short menuID, short menulItem) ; 
void SetMCEntries (short numEntries, MCTablePtr menuCEntries); 


void DeleteMCEntries (short menuID, short menulItem) ; 


Application-Defined Routine 


pascal 
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void MyMenuDef (short message, MenuHandle theMenu, 
Rect *menuRect, Point hitPt, 
short *whichItem) ; 
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Assembly-Language Summary 


Data Structures 


The Menu Information Data Structure 


0 menuID word number that identifies the menu 
2 menuWidth word width (in pixels) of the menu 
4 menuHeight word height (in pixels) of the menu 
6  menuDefHandle long menu definition procedure 
10 menuEnable long enable flags 
14 menuData 256 bytes menu title followed by menu item information 





Global Variables 




















AtMenuBottom The pixel value at the bottom of the scrollable menu. 

MBarEnable Contains 0 if all menus in the current menu bar belong to an application; 
contains a nonzero value if all menus belong to a desk accessory. 

MBarHeight Contains current height of the menu bar, in pixels. 

MBarHook Address of routine that MenuSelect calls repeatedly while the mouse button 
is down. 

MenuCInfo Contains a handle to application’s menu color information table. 

MenuDisable Contains the menu ID and item number of the last item chosen, regardless of 
whether the item was disabled or enabled. 

MenuFlash Contains the current count (number of times) a menu item blinks when chosen 
by the user. 

MenuHook Address of routine that MenuSelect calls after a menu title is highlighted and 
the menu rectangle is calculated but before the menu is drawn. 

TheMenu Contains the menu ID of the highlighted menu in the menu bar. 

TopMenultem The pixel value at the top of the scrollable menu. 


Result Codes 








noErr 0 No error 

paramErr -50 Error in parameter list 
memFullErr -108 Not enough room in heap zone 
resNotFound -192 Unable to read resource 
hmHelpManagerNotInited -855 Help menu not set up 
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This chapter describes how your application can use the Window Manager to create and 
manage windows. 


A Macintosh application uses windows for most communication with the user, from 
discrete interactions like presenting and acknowledging alert boxes to open-ended 
interactions like creating and editing documents. Users generally type words and 
formulas, draw pictures, or otherwise enter data in a window on the screen. Your 
application typically lets the user save this data in a file, open saved files, and view 
the saved data in a window. See the chapter “Introduction to File Management” in 
Inside Macintosh: Files for more information about handling files. 


A window can be any size or shape, and the user can display any number of windows, 
within the limits of available memory, on the screen at once. 


The Window Manager defines a set of standard windows and provides a set of routines 
for managing them. The Window Manager helps your application display windows that 
are consistent with the Macintosh user interface. See Macintosh Human Interface Guidelines 
for a detailed description of windows and their behavior. 


You typically store information about your windows in resources. This chapter describes 
the standard window resources. For general information on resources, see the chapter 
“Introduction to the Macintosh Toolbox” in this book. For information on Resource 
Manager routines, see the chapter “Resource Manager” in Inside Macintosh: More 
Macintosh Toolbox. 


The Window Manager itself depends on QuickDraw, the part of the Macintosh system 
software that handles quick manipulation of graphics. QuickDraw supports drawing 
into graphics ports, which are individual and complete drawing environments with 
independent coordinate systems. Each window represents a graphics port, which is 
described in Inside Macintosh: Imaging. 


To maintain its windows, your application needs to know what actions the user is taking 
on the desktop. It receives this information through events, which are messages that 
describe user actions and report on the processing status of your application. This 
chapter describes the events that affect window display and considers mouse-down and 
keyboard events as they relate to windows. For a complete description of events and 
how your application handles them, see the chapter “Event Manager” in this book. 


Most document windows contain controls, which are screen images the user 
manipulates to control the display or the behavior of the application. This chapter 
illustrates the controls most commonly used in windows. For more information on 
creating and responding to controls, see the chapter “Control Manager” in this book. 


You use the Window Manager to create and display a new window when the user 
creates a new document or opens an existing document. When the user clicks or holds 
down the mouse button while the cursor is in a window created by your application, 
you use the Window Manager to determine the location of the mouse action and to 
alter the window display as appropriate. When the user closes a window, you use the 
Window Manager to remove the window from the screen. 
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This chapter describes how the Window Manager supports windows and then explains 
how you can use the Window Manager to 


m create and display windows 
m handle events in windows 
m change the display when the user moves or resizes windows 


m remove windows 
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A window is a user interface element, an area on the screen in which the user can enter 
or view information. 


The user can have multiple windows on the desktop at once, from a number of different 
applications. The user can change the size and location of most windows and can place 
windows entirely or partially in front of other windows. Figure 4-1 shows a few 
windows on the desktop. 


Figure 4-1 Multiple windows 





loma prieta 
32 items 244.1 MBindisk 159.2 MB availa 





Window 1 
thiswindow: WindowPtr; 


BEGIN 
part := Findwindow(event.where, thiswind 
CASE part OF 
inMenuBar; {mouse dowr 
BEGIN 


MyAdjustMenus; {first make 








DoMenuCommand(MenuSelect(event 
END; 
inSyswindow: {mouse dow 
SystemClick(event, thiswindow); 


Your application typically creates document windows that allow the user to enter and 
display text, graphics, or other information. For an illustration of a document window in 
full color, see Plate 1 at the beginning of this book. 
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A document window is a view into the document—if the document is larger than the 
window, the window is a view of a portion of the document. Your application can put 
one or more windows on the screen, each window showing a view of a document or of 
auxiliary information used to process the document. 


The Window Manager defines and supports a set of standard window elements through 
which the user can manipulate windows. It’s important that your application follow the 
standard conventions for drawing, moving, resizing, and closing windows. By 
presenting the standard interface, you make experienced users instantly familiar with 
many aspects of your application, allowing them to focus on learning its unique features. 


Figure 4-2 illustrates a standard document window and its elements. 


Figure 4-2 A document window 


Close box Title bar Foor bax 








Window 1 





Scroll arrow 
Sorell bax 


Scroll bar 


Scroll arrow 
Size box 





The title bar displays the name of the window and indicates whether it’s active or not. 
The Window Manager displays the title of the window in the center of the title bar, in the 
system font and system font size. If the system font is in the Roman script system, the 
title bar is 20 pixels high. 


When the user creates a new document, you ordinarily display a new document window 
with the title “untitled”, spelled in lowercase letters. If the user creates a second new 
document window without saving the first, you title the second window “untitled 2”, 
with a space between the word and the number. Continue to add 1 to the number in the 
title as long as the user continues to create new windows without saving previously 
numbered, untitled windows. 


When the user opens a saved document, you assign the document's filename to the 
window in which it is displayed. 


The user expects to move a window by dragging it by its title bar. You can support 
moving the window by calling the Window Manager’s DragWindow procedure, as 
described in “Moving a Window” on page 4-53. 
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The close box offers the user a quick way to close a window. You can use the 
TrackGoAway function to track mouse activity in the close box and the CloseWindow 
and DisposeWindow procedures to close windows. Closing windows is described in 
“Closing a Window” beginning on page 4-60. 


The zoom box offers the user a quick way to switch between two different window sizes. 
You use the TrackBox function to track mouse activity in the zoom box and the 
ZoomWindow procedure to zoom windows. Zooming windows is described in 

“Zooming a Window” beginning on page 4-53. 


The size box lets the user change the size and dimensions of the window. You use the 
GrowWindow function to track mouse activity in the size box and the SizeWindow 
procedure to resize windows. Sizing windows is described in “Resizing a Window” 
beginning on page 4-57. 


The scroll bars let the user see different parts of a document that contains more 
information than can be displayed at once in the window. Although the Macintosh user 
interface guidelines specify that you place scroll bars on the right and lower edges of a 
window that needs them, scroll bars are not part of the window structure. You create and 
control the scroll bars through the Control Manager, described in the chapter “Control 
Manager” in this book. 


The content region is the part of the window in which your application displays the 
contents of a document, the size box, and the window controls. 


The window frame is the part of the window drawn automatically by the Window 
Manager—the title bar, including the close box and zoom box, and the window’s outline. 


The structure region is the entire screen area occupied by a window, including the frame 
and content region. (See Figure 4-10 on page 4-12.) 


Active and Inactive Windows 


The window in which the user is currently working is the active window. The active 
window is the frontmost window on the desktop. It is identified visually by the “racing 
stripes” in its title bar. 


The active window is the target of keyboard activity. It often contains a blinking 
insertion point (also called the caret) marking the place where new text or graphics will 
appear. When the user selects text in an active window, your application should 
highlight the text with inverse video; if the window becomes inactive, you remove the 
highlighting. You can use a secondary selection technique, such as an outline, to mark a 
selection in an inactive window. You display scroll bars only in the active window. 
Figure 4-3 illustrates a sample document window in active and inactive states. 


Except for the active window, all document windows on the desktop, whether they 
belong to your application or another, are inactive. Your application can process 
documents in inactive windows, but only the active window interacts with the user. 
For example, if the user chooses Save from the File menu, your application saves 
only the document in the active window. 
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Figure 4-3 


Dozoomilindoi,; 
Dozoomwindow(this window: 
windowPtr; zoomlnOrQut: Integers; 

VAR 
gdNthDevice, gdZoomOnThisbevice: 
GOHand1e; 
savePort: GrafPtr; 
windFect, zoomRect, theSect: Rect; 
Eee Lonigint,; 


wTitleHeight: Integer; 
sectFlag: Boolean; 
BEGIN 
GetPort(savePort); 
SetPort(this window): 
EraseRect(thiswindow* portRect): 
IF zoomInQrQut = ingoomOut THEN 


BEGIN 


Active document window 





Active and inactive document windows 



















i DoZoomwWindow(thiswindaw: 
rwindowPtr; zoominOrQut: Integer}; 
i WAR 
gdNthDevice, gdZoomOnThisbevice: 
GOHand1e; 
savePort: GrafPtr; 
windFect, zoomRect, theSect: Rect; 
sectArea, greatestArea: Longint; 
i wTitleHeight: Integer; 
: sectFlag: Boolean; 
| BEGIN 
i GetPort(savePort); 
i SetPort(this window): 
i EraseRect(thiswindow*portRect); 
IF zoomInQrQut = ingoomOut THEN 
i BEGIN 


Inactive document window 


To make a window active, the user clicks anywhere in its contents or frame. When 
the user activates one of your windows, you call the Window Manager to highlight 
the window frame and title bar; you activate the controls and window contents. 

As a window becomes active, it appears to the user to move forward, in front of all 


other windows. 


When the user clicks in an inactive document window, you should make the window 
active but not make any selections in the window in response to the click. To make a 
selection in the window, the user must click again. This behavior protects the user from 
losing an existing selection unintentionally when activating a window. 


Note 


The Finder makes selections in response to the first click in an inactive 
window, because this action is more natural for the way Finder 
windows are used. You might find that users expect the first click to 
cause a selection in some other special-purpose windows created by 
your application. This behavior is seldom appropriate in document 


windows. 


When a window that belongs to your application becomes inactive, the Window 
Manager redraws the frame, removing the highlighting from the title bar and hiding 
the close and zoom boxes. Your application hides the controls and the size box and 
removes highlighting from application-controlled elements. 


When the user reactivates a window, reinstate the window as it was before it was 
deactivated. Draw the scroll box in the same position and restore the insertion point or 


highlight the previous selection. 
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Types of Windows 


Because windows have so many uses, their appearances vary. The Window Manager 
defines a number of window types that meet the basic needs of most applications. A 
window type is the general description of how a window looks and behaves. Some 
windows have title bars and others don’t, for example, and windows can have almost 
any combination of the window-manipulation elements: close box, zoom box, and 
size box. 


This section describes the nine basic window types supported by the Window Manager 
and their uses. You can create windows of these types by specifying one of the window 
type constants: zoomDocProc, dBoxProc, altDBoxProc, plainDBoxProc, 











movableDBoxProc, noGrowDocProc, documentProc, zoomNoGrow, and rDocProc. 
For instructions for creating windows, see “Creating a Window” beginning on page 4-25. 


To give the user maximum flexibility and control, you can use the zoomDocProc 
window type for your document windows. A zoomDocP roc window supports all of the 
window-manipulation elements shown in Figure 4-2 on page 4-5: title bar, close box, 
zoom box, and size box. The Window Manager does not necessarily draw the close box 
and size box, however. You must call the Window Manager’s DrawGrowIcon procedure 
to draw the size box, and you can optionally suppress the close box when you create the 
window. For more information on defining a window’s characteristics, see “Creating a 
Window” beginning on page 4-25. 


Figure 4-4 illustrates a window of type zoomDocProc with a close box, as drawn by the 
Window Manager before you add the size box and scroll bars. 


Figure 4-4 A window of type zoomDocProc 


untitled 
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In most cases, a window of type zoomDocP roc should contain both a close box and a 
size box. When the related document contains more data than fits in the window, you 
activate the scroll bars and adjust them to show where in the document the user is 
working. Figure 4-5 illustrates a window of type zoomDocProc with a size box and 
scroll bars. 
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Figure 4-5 A window of type zoomDocProc, with size box and inactive scroll bars 


untitled 





You also use windows to display alert boxes and dialog boxes. This section describes the 
window types used for alert boxes and dialog boxes. For more thorough descriptions of 
the different kinds of alert boxes and dialog boxes, see the chapter “Dialog Manager” in 
this book. 


Alert boxes and fixed-position modal dialog boxes contain no window-manipulation 
elements. The user cannot move, resize, zoom, or close them manually. An alert box or a 
modal dialog box remains on the screen as the active window until the Dialog Manager 
or your application removes it—usually when the user completes the interaction by 
clicking one of the buttons. Figure 4-6 illustrates the three window types available for 
alert boxes and fixed-position modal dialog boxes. 











Figure 4-6 Window types for alert boxes and fixed-position modal dialog boxes 
dBox Proc altDRoxPre ¢ plainDBoxProc 


When you want to let the user move a modal dialog box window—in order, for example, 
to see text that might be obscured by the window—you can implement a movable modal 
dialog box. A movable modal dialog box cannot be resized, closed, or zoomed, but it can 
be moved. Figure 4-7 on the next page illustrates the movableDBoxProc window type. 
Like a fixed-position modal dialog box, the movable modal dialog box remains active 
until the user completes the dialog. 
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Figure 4-7 A window of type movableDBoxProc 


untitled 





mevableDRexPre c 


Whenever possible, avoid modal dialog boxes and instead use modeless dialog boxes, 
which allow the user to perform other tasks without dismissing the dialog box. 
Windows of type noGrowDocProc, used for displaying modeless dialog boxes, can be 
moved or closed but not resized or zoomed. You can implement modeless dialog boxes 
with other window types if necessary, but it’s easier to conform to the user interface 
guidelines if you keep your dialog box windows as simple as possible. Figure 4-8 
illustrates the modeless dialog box window. 


Figure 4-8 A window of type noGrowDocProc 
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The Window Manager also supports a few window types that are seldom used. The 
documentProc window type, for example, has a title bar and supports a close box and 
size box but no zoom box. The zoomNoGrow window type is virtually never appropriate: 
zoomNoGrow supports a close box and a zoom box, but not a size box. The rDocProc 
window type is a rounded-corner window with a title bar and a close box; it is used by 
desk accessories. Figure 4-9 illustrates these three seldom-used window types. 


The window definition function defines the general appearance and behavior of a 
window. The system software and various Window Manager routines call a window’s 
window definition function when they need to perform certain window-dependent 
actions, such as drawing or resizing a window’s frame. 
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Figure 4-9 Seldom-used window types 
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The Window Manager supplies two standard window definition functions that handle 
the nine standard window types. A window definition function draws the window’s 
frame, draws the close box and window title (if any), determines which region the cursor 
is in within the window, calculates the window’s structure and content regions, draws 
the window’s zoom box (if any), draws the window’s size box (if any), and performs any 
special initialization or disposal tasks. 


A single window definition function can support up to 16 different window types. The 
window definition function defines a variation code, an integer from 0 through 15, for 
each window type it supports. 


A window definition ID is a single value incorporating both the window’s definition 
function and its variation code. (The resource ID of the window definition function 

is stored in the upper 12 bits of the integer, and the variation code is stored in the 
lower 4 bits.) The window-type constants described in this section are in fact window 
definition IDs. 











Window 
Constant definition ID Description 
documentProc 0 movable, sizable window, no zoom box 
dBoxProc 1 alert box or modal dialog box 
plainDBox 2 plain box 
altDBoxProc 3 plain box with shadow 
noGrowDocProc 4 movable window, no size box or zoom box 
movableDBoxProc 5 movable modal dialog box 
zoomDocProc 8 standard document window 
zoomNoGrow 12 zoomable, nonresizable window 
rDocProc 16 rounded-corner window 


You can provide your own window definition function if you need a window with 
unusual characteristics, as described in “The Window Definition Function” beginning 
on page 4-120. Always be careful to conform window behavior to the guidelines in 
Macintosh Human Interface Guidelines. 
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Window Regions 


The Window Manager recognizes a number of different special-purpose window 
regions, which are defined by either the Window Manager or the window definition 
functions. 


The most obvious window regions are the parts of the visible window that the user 
manipulates to control the display. These window regions correspond to the standard 
window parts. The drag region is the area occupied by the title bar, except for the close 
box and zoom box. (The user moves the window by dragging it by its title bar.) The size 
region, close region, and zoom region are the areas occupied by the size box, close box, 
and zoom box, respectively. 


When the user presses the mouse button while the cursor is in one of your windows, you 
use the Window Manager function FindWindow to determine the region in which the 
mouse-down event occurred. (The FindWindow function calls the window’s window 
definition function, which defines and interprets the window-manipulation regions.) 
Depending on the result, you then call the appropriate Window Manager routine or your 
own routine for handling the event. For more information about determining where the 
cursor is when the user presses the mouse button, see “Handling Mouse Events in 
Windows” on page 4-42. For discussions of how to use the Window Manager routines 
for moving, sizing, closing, and zooming windows, see “Moving a Window” beginning 
on page 4-53 and the sections that follow it. 


The Window Manager also makes a broad distinction between the parts of the window 

it draws automatically and the parts drawn by your application. The Window Manager 
draws the window frame—the title bar, including the close box and zoom box, and 

the window’s outline. (The Window Manager also draws the size box, but only when 
your application calls the DrawGrowIcon procedure.) Your application is responsible for 
drawing the content region—that is, the part of the window in which the contents 

of a document, the size box, and the window controls (including the scroll bars) 

are displayed. 


The entire screen area occupied by a window, including the window outline, title bar, 
and content region, is the structure region. Figure 4-10 illustrates the frame, content 
region, and structure region of a window. 


Figure 4-10 Window frame, content region, and structure region 
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The drawing region of a graphics port associated with a window encompasses only the 
window’s content region. 


As the user creates, moves, resizes, and closes windows on the desktop, portions of 
windows may be obscured and uncovered. The Window Manager keeps track of these 
changes, accumulating a dynamic region known as the update region for each window. 
The update region contains all areas of a window’s content region that need updating. 
The Event Manager periodically scans the update regions of all windows on the desktop, 
generating update events for windows whose update regions are not empty. When your 
application receives an update event, it redraws the update region. Both your application 
and the Window Manager can manipulate a window’s update region. The sections 
“Updating the Content Region” on page 4-40 and “Maintaining the Update Region” on 
page 4-41 describe how the Window Manager and your application track and use the 
update region. 


Dialog Boxes and Alert Boxes 


Macintosh applications use alert boxes and dialog boxes to give the user messages and 
to solicit information. A text-processing application, for example, might display an 
alert box telling the user that a newly inserted graphic does not fit within the page 
boundaries. It might display a dialog box in which the user can specify margins, tabs, 
and other formatting information. (The chapter “Dialog Manager” in this book explains 
how to use the various kinds of alert boxes and dialog boxes.) 


Alert boxes and dialog boxes are merely special-purpose windows. You can handle all 
alert boxes and most modal dialog boxes through the Dialog Manager, which itself calls 
the Window Manager. You supply the Dialog Manager with lists of the items in your 
alert boxes and dialog boxes, and the Dialog Manager displays the windows, tells you 
which items the user is manipulating, and disposes of the windows when the user is 
done. Your application provides the code that responds to the user’s selections in the 
alert and dialog boxes. 


Although you can specify any window type for your alert boxes and modal dialog 
boxes, the Dialog Manager functions that handle alert boxes and modal dialog boxes do 
not support window manipulation. You should therefore use one of the window types 
without a title bar or size box, most typically the dBoxProc window type, for alert boxes 
and modal dialog boxes. (When the user is responding to a modal dialog box, 
mouse-down events outside the menu bar or the content region of the dialog box result 
only in the sounding of the system alert. Note that the Process Manager does not 
perform major switching while the ModalDialog procedure is handling events.) 


You use the movableDBox window type for movable modal dialog boxes. As described 
in the chapter “Dialog Manager” in this book, your application can use the Dialog 
Manager to help handle events in a movable modal dialog box. Your application, 
however, must handle window-manipulation events—ordinarily only the moving of the 
movable modal dialog box window. 
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Use the noGrowDocProc window type for modeless dialog boxes. You typically use 
the Dialog Manager to handle events in a modeless dialog box, much like events in 

a movable modal dialog box. Your application handles window-manipulation events in 
modeless dialog boxes just as it handles them in document windows. 


If you use complex dialog boxes, you might find it’s more efficient to use the Window 
Manager and other parts of the Toolbox, instead of the Dialog Manager, to create and 
manage your own dialog box windows. Again, see the chapter “Dialog Manager” in this 
book for a list of characteristics to consider when evaluating the complexity of a dialog 
box and for examples of customized dialog boxes. 


Controls 


Most windows contain controls, which are screen images that the user manipulates to 
control the display or the behavior of the application. The most common control in a 
document window is the scroll bar, illustrated in Figure 4-11. 


Figure 4-11 Scroll bars 
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You use scroll bars to show the relative position, within the entire document, of the 
portion of the document displayed in the window. You should allow the user to drag the 
scroll box or click in the gray areas or the scroll arrows to move parts of the document 
into and out of the window. You activate scroll bars in a window any time there is more 
data than can be shown at one time in the space available. 


You use the Control Manager to create, display, and manipulate the scroll bars and any 
other controls in your windows. Each control “belongs” to a window and is displayed 
within the graphics port that represents that window. For each window your application 
creates, the Window Manager maintains a control list, a series of entries pointing to the 
descriptions of the controls associated with the window. 


Introduction to Windows 


CHAPTER 4 


Window Manager 


Most alert boxes and dialog boxes contain buttons, rounded rectangles that cause 

an immediate or continuous action when clicked, and most dialog boxes contain 
additional screen images, like radio buttons, that display and retain settings. Figure 4-12 
illustrates a dialog box with buttons, radio buttons, and a number of other controls and 
dialog items. 


Figure 4-12 Controls in a dialog box 
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Buttons ordinarily appear only in alert boxes and dialog boxes. Most of the other 
elements illustrated in Figure 4-12 appear only in dialog boxes. If you use the Dialog 
Manager to create your alert boxes and dialog boxes, it draws your controls for you and 
lets you know when the user has clicked one of them. You can, however, call the Control 
Manager yourself to display and track buttons and other controls in any windows your 
application creates. You can also write your own control definition functions to create 
and control other kinds of controls. For a complete description of how to create and 
support controls, see the chapter “Control Manager” in this book. 


Windows on the Desktop 


Multiple windows, from different applications, can appear simultaneously on the 
desktop. The Window Manager tracks all windows, using its own private data structure 
called the window list. Entries appear in the window list in their order on the desktop, 
beginning with the frontmost, active window. When the user changes the ordering of 
windows on the desktop, the Window Manager generates events telling your application 
to activate, deactivate, and redraw windows as necessary. The Window Manager 
prevents you from drawing accidentally in the windows of other applications. 
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The user can interact with only one application at a time. The application with which the 
user is interacting (that is, the application that owns the window in which the user is 
working) is the active application, or foreground process, and the others are inactive 
applications, or background processes. One way the user can switch applications is by 
clicking in a window that belongs to a background process. The Process Manager then 
generates events telling the previously active application that it’s about to be suspended 
and telling the newly active application that it can resume processing. (For more infor- 
mation about the workings of foreground and background processes and about the 
events that support simultaneous running of multiple applications, see the chapter 
“Event Manager” in this book.) 


Your application is likely to have multiple windows on the desktop at once: one or more 
document windows, possibly one or more dialog box windows, and possibly some other 
special-purpose windows. The section “Managing Multiple Windows” beginning on 
page 4-23 suggests a technique for keeping track of multiple windows. 


On the original Macintosh computer, the desktop area was limited to a single screen of 
known dimensions. Contemporary systems, however, can support multiple monitors of 
various sizes and capabilities. To place its windows in the appropriate place on the 
desktop, your application must pay attention to what screen space is available and 
where the user is working. For the rules governing window placement, see Macintosh 
Human Interface Guidelines. For techniques for managing windows on multiple screens, 
see “Positioning a Document Window on the Desktop” beginning on page 4-30. 


The entire area of the desktop—that is, the screen area that is not occupied by the menu 
bar—is known as the gray region. The Window Manager maintains a pointer to the gray 
region in a global variable named GrayRgn; you can retrieve a pointer to the gray region 
with the Window Manager function Get GrayRgn. 


About the Window Manager 


4-16 


The Window Manager provides a complete set of routines for creating, moving, resizing, 
and otherwise manipulating windows. It also provides lower-level support by managing 
the layering of windows on the desktop and by alerting your application to desktop 
changes that affect its windows. Your application and the Window Manager work 
together to provide the user with a consistent window interface. 


When, for example, the user presses the mouse button while the cursor is in the drag 
region of a window’s title bar, you can call the DragWindow procedure, which moves a 
dotted outline of the window around the screen in response to mouse movements. When 
the user releases the mouse button, DragWindow calls the MoveWindow procedure, 
which redraws the window in its new location. If part or all of an inactive window 
belonging to your application is exposed by the move, the Window Manager triggers an 
update event that tells your application to redraw the exposed region. 


Similarly, if the user clicks in an inactive window, you can call the SelectWindow 
procedure. SelectWindow adjusts the window highlighting and layering and 
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also generates activate events that tell your application which windows to activate 
and deactivate. 


The Window Manager has built-in support for the nine basic window types described in 
“Types of Windows” beginning on page 4-8. When you are using one of these window 
types, the Window Manager draws the window’s frame, determines what region of the 
window the cursor is in, calculates the window’s structure and content regions, draws 
the window’s size box, draws the window’s close box and zoom box, and performs any 
special initialization or disposal tasks. If necessary, you can write your own window 
definition function to handle other types of windows. 


Graphics Ports 


Each window represents a QuickDraw graphics port, which is a drawing environment 
with its own coordinate system. (See Inside Macintosh: Imaging for a complete description 
of graphics ports and coordinate systems.) When you create a window, the Window 
Manager creates a graphics port in which the window’s contents are displayed. 


The location of a window on the screen is defined in global coordinates—that is, 
coordinates that reflect the entire potential drawing space. QuickDraw and Color 
QuickDraw recognize a coordinate plane whose origin is the upper-left corner of the 
main screen, whose positive x-axis extends rightward, and whose positive y-axis extends 
downward. In QuickDraw, the horizontal offset is ordinarily labeled h, and the vertical 
offset v. Figure 4-13 illustrates the QuickDraw global coordinate system. 


Figure 4-13 The QuickDraw global coordinate plane 
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Note 

The orientation of the vertical axis, while convenient for computer 
graphics, differs from mathematical convention. Also, the coordinate 
plane is bounded by the limits of QuickDraw coordinates, which range 
from —32,768 to 32,767. 


QuickDraw stores points and rectangles in its own data structures of 

type Point and Rect. In these structures, the vertical coordinate (v) 

appears first, followed by the horizontal coordinate (h). Most, but not 

all, QuickDraw routines that handle points require you to specify the 

coordinates in this order. 

When QuickDraw creates a new graphics port (usually because you’ve created a new 
window through the Window Manager), it defines a bounding rectangle for the port, in 
global coordinates. Ordinarily, the bounding rectangle represents the entire area of the 
screen on which the window appears. The bounding rectangle is stored in the graphics 
port data structure, in the bounds field of a structure called a pixel map in Color 
QuickDraw and a bitmap in QuickDraw. 


The graphics port data structure also includes a field called port Rect, which defines 
a rectangle to be used for drawing. In a graphics port that represents a window, the 
portRect rectangle represents the window’s content region. 


Note 

When you place a window on the screen, you specify the location of its 
content region, in global coordinates. Remember to allow space for 

the window’s title bar. On the main screen, remember to leave space for 
the menu bar. In the Roman script system, both the standard document 
title bar and the menu bar are 20 pixels high. You can determine the 
height of the menu bar with the Menu Manager GetMBarHeight 
function. You can calculate the height of the title bar by comparing the 
top of the window’s structure region with the top of the window’s 
content region. See Listing 4-12 on page 4-55 for a sample procedure that 
considers the menu bar and title bar when placing a window on the 
screen. 


Within the port rectangle, the drawing area is described in local coordinates—that is, in 
the coordinate system defined by the port rectangle. You draw into a window in local 
coordinates, without regard to the window’s location on the screen (which is described 
in global coordinates). Figure 4-14 illustrates the local and global coordinate systems for 
a sample window 180 pixels high by 300 pixels wide, placed with its content region 

70 pixels down and 60 pixels to the right of the upper-left corner of the screen. 


When the Window Manager creates a window, it places the origin of the local coordinate 
system at the upper-left corner of the window’s port rectangle. You can redefine 

the coordinates of the port rectangle’s upper-left corner with the QuickDraw 

procedure Set Origin. 


The Event Manager describes mouse events in global coordinates, and you do most of 
your window manipulation in global coordinates. You generally display user data and 
manipulate your controls in local coordinates. When you need to convert between the 
two, you can call the QuickDraw functions GlobalToLocal and LocalToGlobal, 
described in Inside Macintosh: Imaging. 


About the Window Manager 


CHAPTER 4 


Window Manager 


Figure 4-14 A window’s local and global coordinate systems 
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Window Records 


Each window has a number of descriptive characteristics such as a title, control list, and 
visibility status. The Window Manager stores this information in a window record, 
which is a data structure of type WindowRecord. 


The window record includes 
m the window’s graphics port data structure 


m the window’s class, which specifies whether it was created directly through the 
Window Manager or indirectly through the Dialog Manager 


gm the window title 


m aseries of flags that specify whether the window is visible, whether it’s highlighted, 
whether it has a zoom box, and whether it has a close box 


™ pointers to the structure, content, and update regions 

m= ahandle to the window’s definition function 

m= ahandle to the window’s control list 

m an optional handle to a picture of the window’s contents 

m areference constant field that your application can use as needed 


The window record is described in detail in “The Color Window Record” beginning on 
page 4-65. 


The first field in the window record is the window’s graphics port. The WindowPtr data 
type is therefore defined as a pointer to a graphics port. 


TYPE WindowPtr = GrafPtr; 
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You draw into a window by drawing into its graphics port, passing a window pointer to 
the QuickDraw drawing routines. You also pass window pointers to most Window 
Manager routines. 


You don’t usually need to access or directly modify fields in a window record. When you 
do, however, you can refer to them through the WindowPeek data type, which is a 
pointer to a window record. 


TYPE WindowPeek = ‘*WindowRecord; 


The close box, drag region, zoom box, and size box are not included in the window 
record because they don’t necessarily have the formal data structure for regions 

as defined in QuickDraw. The window definition function determines where these 
regions are. 


Your application seldom accesses a window record directly; the Window Manager 
automatically updates the window record when you make any changes to the window, 
such as changing its title. The Window Manager also supplies routines for changing and 
reading some parts of the window record. 


Color Windows 


Since the introduction of Color QuickDraw, the Window Manager has supported color 
windows. Color windows are displayed in color graphics ports, as described in Inside 
Macintosh: Imaging. The color window record is exactly like the window record described 
in “Window Records” on page 4-19, except that it contains a color graphics port instead 
of a monochrome graphics port. 


Whether or not your application uses color explicitly, and whether or not a color monitor 
is currently installed, your application should work with color windows whenever Color 
QuickDraw is available. Once you have created a window, you can use the window 
record and window pointer for a color window interchangeably with the window record 
and window pointer for a monochrome window. 


Ona monitor that is set to display 4-bit color or greater, the Window Manager 
automatically displays the window title and parts of the frame and controls in color (or 
gray scale, depending on the capabilities of the monitor). The user can adjust these colors 
through the Color control panel. Except in unusual circumstances, your application 
should not try to change the colors of the window frame. On a monitor that’s set to 
display 1-bit color, the Window Manager draws the window title, frame, and controls in 
black and white. 


Various elements of a window’s colors are controlled by the window color table, which 
contains a series of part codes for different window elements and the RGB values 
associated with each part. 


Because the user can select window display colors for the entire desktop, and because 
the Window Manager performs some complex display calculations automatically if you 
don’t override it, your application typically uses the default system window color table. 
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If your application explicitly controls the colors used in a window, however, you can 
define your own window color tables. 


You define a window color table for a window by providing a window color table 
resource (that is, a resource of type 'wctb') with the same resource ID as the window’s 
‘WIND ' resource. The Window Manager creates a window color table when it creates 
the window record. The Window Manager maintains its own linked list, using auxiliary 
window records, which associates your application’s windows with their corresponding 
window color tables. The window color table and the auxiliary window record are 
described in “The Window Color Table Record” beginning on page 4-71 and “The 
Auxiliary Window Record” beginning on page 4-73. 


Except in unusual circumstances, your application doesn’t need to manipulate window 
color tables or the auxiliary window record. 


For compatibility with other applications in the shared environment, your application 
should not manipulate system color tables directly but should use the Palette Manager, 
as described in Inside Macintosh: Imaging. If your application provides its own window 
and control definition functions, they should apply the user’s desktop color choices just 
as the default definition functions do. 


Events in Windows 


Events are messages that describe user actions and report on the processing status of 
your application. The Window Manager generates two kinds of events: activate 

events and update events. Activate events tell your application that a specified 
window is becoming active or inactive. Update events tell your application that it 
must redraw part or all of a window’s content region. The section “Handling Events in 
Windows” beginning on page 4-41 describes when these events occur and how your 
application responds. 


One of the basic functions of the Window Manager is to report where the cursor is 
when your application receives a mouse-down event. The Window Manager function 
F indWindow tells your application whether the cursor is in a window and, if it’s in 
a window, which window it’s in and where in that window (that is, the title bar, the 
drag region, and so on). You can use the FindWindow function as a first filter for 
mouse-down events, separating events that merely affect the window display from 
events that manipulate user data. 


The Window Manager also provides a set of routines that help you implement the 
standard window-manipulation conventions: 


User action Application response 

Dragging the title bar Moves the window 

Dragging the size box Resizes the window 

Clicking the zoom box Toggles the window between two sizes and locations, 


known as the user state and the standard state 


Clicking the close box Closes the window 
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The next section, “Using the Window Manager,” describes how you can use the Window 
Manager to move, resize, zoom, and close windows. 


You can call the Control Manager to handle events in window controls, as described in 
the chapter “Control Manager” in this book. If you use the Dialog Manager for your alert 
boxes and modal dialog boxes, the Dialog Manager handles keyboard activity and 
mouse events in these windows. You can also use the Dialog Manager to handle 
keyboard activity and mouse events in the content region of movable modal dialog 
boxes and modeless dialog boxes. Your application, however, must handle mouse events 
in the title bar and close box of a movable modal or modeless dialog box. 


When your application is active, a mouse-down event in a window belonging to any 
other application, including the Finder, switches your application to the background 
(unless there’s an alert box or a modal dialog box pending, in which case the Dialog 
Manager merely sounds the system alert). 
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Virtually every Macintosh application uses the Window Manager, both to simplify 
the display and management of windows and to retrieve basic information about 
user activities. 


Your application works in conjunction with the Window Manager to present the 
standard user interface for windows. When the user clicks in an inactive window 
belonging to your application, for example, you can call the procedure SelectWindow, 
which highlights the newly active window, removes the highlighting from the 
previously active window, and generates the activate events that trigger the activation 
and deactivation of the two affected windows. 


Your application can also use Window Manager routines to handle direct window 
manipulation. For example, if the user presses the mouse button when the cursor is in 
the title bar of a window, you can call the DragWindow procedure to track the mouse 
and drag an outline of the window on the screen until the user releases the mouse button. 


You typically create windows from window resources, which are resources of type 
'WIND'. The Window Manager supports the nine types of windows described in “Types 
of Windows” beginning on page 4-8. (You can also write your own window definition 
functions to support your own window types. Window definition functions are stored as 
resources of type 'WDEF'.) Alert box windows and dialog box windows use alert 
('ALRT'), dialog ('DLOG"), and item list ('DITL") resources; the chapter “Dialog 
Manager” describes how to create these resources. Most windows contain controls, 
which are defined through control ('CNTL") resources; the chapter “Control Manager” 
describes how to create control resources. 
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Your application typically uses the Window Manager in conjunction with both the 
Control Manager and the Dialog Manager. You use the Control Manager to define, draw, 
and manipulate controls in your windows. If your window includes scroll bars, for 
example, you can use the TrackCont rol function to track the mouse while the user 
drags the scroll box. You can use the Dialog Manager to create, display, and track events 
in alert boxes and dialog boxes. 


System 7 provides help balloons for the window frame—that is, the title bar, zoom box, 
and close box—of a window created with one of the standard window definition 
functions. You should provide help balloons for your window content region—that is, 
the size box, controls, and data area—and for the window frames of any window types 
you define. See the chapter “Help Manager” in Inside Macintosh: More Macintosh Toolbox 
for a description of how to use help balloons. 


Before using the Window Manager, you must call the procedure InitGraf to initialize 
QuickDraw, the procedure InitFonts to initialize the Font Manager, and finally the 
procedure InitWindows to initialize the Window Manager. 


Managing Multiple Windows 


Your application is likely to have multiple windows on the desktop at once: one or more 
document windows, possibly one or more dialog boxes, and possibly some special- 
purpose windows of your own. Only one window is active at a time, however. 


When your application receives an event, it responds according to what kind of window 
is currently active and where the event occurred. When it receives a mouse-down event 
in the content region of an active document window, your application follows its own 
conventions: inserting text, making a selection, or adding graphics, for example. When it 
receives a mouse-down event in the menu bar, your application enables and disables 
menu items as appropriate—which again depends on what kind of window is active and 
what is selected in that window. If the user has the insertion point in an editable text 
field in a modal dialog box, for example, the only menu item available might be Paste in 
the Edit menu—and then only if there is something in the scrap to be pasted. 


You can use various strategies for keeping track of different kinds of windows. The 
refCon field in the window record is set aside specifically for use by applications. 
You can use the refCon field to store different kinds of data, such as a number that 
represents a window type or a handle to a record that describes the window. 


The sample code in this chapter—excerpts from the SurfWriter application used 
throughout this book—uses a hybrid strategy: 


m For document windows, the refCon field holds a handle to a document record. 


m For modeless or movable modal dialog boxes, the refCon field holds a number that 
represents a type of dialog box. 


You may well find other approaches more practical. 
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The SurfWriter application stores document information about the user’s data, the 
window display, and the file, if any, associated with the data in a document record. The 
document record takes this form: 


TYPE MyDocRec = 














RECORD 
editRec: TEHandle; {handle to text being edited} 
vScrollBar: ControlHandle; {control handle to the } 

{ vertical scroll bars} 
hScrollBar: ControlHandle; {control handle to the } 

{ horizontal scroll bars} 
fileRefNum: Integer; {reference number for file} 
fileFSSpec: FSSpec; {FSSpec record for file} 
windowDirty: Boolean; {whether data has changed } 

{ since last save} 

END; 
MyDocRecPtr = *“MyDocRec; 
MyDocRecHnd = “MyDocRecPtr; 


The SurfWriter application creates a document record every time it creates a document 
window, and it stores a handle to the document record in the refCon field of the 
window record. (See the chapter “Introduction to File Management” in Inside Macintosh: 
Files for a more complete illustration of how to use document records.) 


When SurfWriter creates a modeless dialog box or a movable modal dialog box, it stores 
a constant that represents that dialog box (that is, it specifies the constant in the dialog 
resource, and the Window Manager sets the refCon field to that value when it creates 
the window record). For example, a refCon value of 20 might specify a modeless dialog 
box that accepts input for the Find command, and a value of 21 might specify a modeless 
dialog box that accepts input for the spelling checker. 


When SurfWriter receives notification of an event in one of its windows, it first 
determines the function of the window and then dispatches the event as appropriate. 
Listing 4-1 illustrates an application-defined routine MyGetWindowType that 
determines the window’s type. 


Note 

The MyGetWindowType function determines the type of a window from 
among a set of application-defined window types, which reflect the 
different kinds of windows the application creates. These window types 
are different from the standard window types defined by the definition 
functions, which determine how windows look and behave. To find out 
which one of the standard window types a window is, call the Window 
Manager function GetWVariant. @ 


The sample code later in this chapter calls the MyGet WindowType function as part of its 
event-handling procedure, described in the section “Handling Events in Windows” 
beginning on page 4-41. 
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Listing 4-1 Determining the window type 


FUNCTION MyGetWindowType (thisWindow: WindowPtr): Integer; 
VAR 
myWindowType: Integer; 


























BEGIN 
IF thisWindow <> NIL THEN 
BEGIN 
myWindowType := WindowPeek (thisWindow) *.windowKind; 
IF myWindowType < 0 THEN {window belongs to } 
MyGetWindowType := kDAWindow { a desk accessory} 
ELSE 
IF myWindowType = userKind THEN {document window} 
MyGetWindowType := kMyDocWindow 
ELSE {dialog window} 
MyGetWindowType := GetWRefCon (window) ; {get dialog ID} 
END 
ELSE 
MyGetWindowType := kNil; 
END; 





Notice that MyGetWindowType checks whether the window belongs to a desk accessory. 
This step ensures compatibility with older versions of system software. When your 
application is running in System 7, it should receive events only for its own windows 
and for windows belonging to desk accessories that were launched in its partition. See 
Inside Macintosh: Memory for information about partitions and Inside Macintosh: Processes 
for information about launching applications and desk accessories. 


Creating a Window 


You typically specify the characteristics of your windows—such as their initial size, 
location, title, and type—in window ('WIND ') resources. Once you have defined your 
window resources, you can call the function Get NewCWindow (or Get NewWindow) to 
create windows. 


Defining a Window Resource 


You typically define a window resource for each type of window that your application 
creates. If, for example, your application creates both document windows and 
special-purpose windows, you would probably define two window resources. Defining 
your windows in window resources lets you localize your window titles for different 
languages by changing only the window resources. (You specify the characteristics of 
alert boxes and dialog boxes with the alert and dialog resources, described in the chapter 
“Dialog Manager” in this book.) 
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Listing 4-2 shows a window resource, in Rez input format, that an application might use 
to create a document window. The resource specifies the attributes for windows created 
from the resource of type 'WIND' with resource ID 128. The system software loads the 
resource into memory immediately after opening the resource file, and the Memory 
Manager can purge the memory occupied by the resource. 


Listing 4-2 Rez input for a window ("WIND") resource for a document window 


#define rDocWindow 128 


resource 'WIND' (rDocWindow, preload, purgeable) { 
{64, 60, 314, 460}, /*initial window size and location*/ 
zoomDocProc, /*window definition ID: */ 
/* incorporates definition function */ 


/* and variation code*/ 


invisible, /*window is initially invisible*/ 
goAway, /*window has close box*/ 

0x0, /*reference constant*/ 
"untitled", /*window title*/ 


staggerParentWindowScreen 
/*optional positioning specification*/ 
}; 


The four numbers in the first element of this resource specify the upper-left and lower- 
right corners, in global coordinates, of a rectangle that defines the initial size and 
placement of the window’s content region. Your application can change this rectangle 
before displaying the window, either programmatically or through an optional 
positioning code described later in this section. When specifying a window’s position on 
the desktop, remember to leave room for the window’s frame and, on the main screen, 
for the menu bar. 


The second element contains the window’s definition ID, which specifies both the 
window definition function that will handle the window and an optional variation code 
that defines a window type. If you are using one of the standard window types 
(described in “Types of Windows” beginning on page 4-8), you need to specify only one 
of the window-type constants listed in “The Window Resource” beginning on page 4-124. 


The third element in the window resource specifies whether the window is initially 
visible or invisible. This element determines only whether the Window Manager 
displays the window when it first creates it, not whether the window can be seen on the 
screen. (A window entirely covered by other windows, for example, might be “visible,” 
even though the user cannot see it.) You typically create new windows in an invisible 
state, build the content area of the window, and then display the completed window by 
calling ShowWindow to make it visible. 
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The fourth element in the window resource specifies whether the window has a close 
box. Only some of the standard window types (zoomDocProc, noGrowDocProc, 
documentProc, zoomNoGrow, and rDocProc) support close boxes. The close-box 
element has no effect if the second field of the resource specifies a window type that does 
not support a close box. The Window Manager draws the close box when it draws the 
window frame. 


The fifth element in the window resource is a reference constant, in which your 
application can store whatever data it needs. When it builds a new window record, the 
Window Manager stores in the refCon field whatever value you specify here. You can 
also put a placeholder here (such as 0x0, in this example) and then set the refCon field 
yourself by calling the SetWRefCon procedure. 


The sixth element in the window resource is a string that specifies the window title. 


The optional seventh element in the window resource specifies a positioning rule that 
overrides the window position specified by the rectangle in the first element. In the 
window resource for a document window, you typically specify the positioning constant 
staggerParentWindowScreen. For a complete list of the positioning constants and 
their effects, see “The Window Resource” beginning on page 4-124. 


The positioning constants are convenient when the user is creating a new document or 
when you're handling your own dialog boxes and alert boxes. When you're creating a 
new window to display a previously saved document, however, the new window 
should appear, if possible, in the same rectangle as the previous window (that is, the 
window used during the last save). For the rules of window placement, see “Positioning 
a Document Window on the Desktop” beginning on page 4-30. 


Use the function Get NewCWindow or GetNewWindow to create a window froma 
"WIND" resource. 


Creating a Window From a Resource 


You typically create a new window every time the user creates a new document, opens a 
previously saved document, or issues a command that triggers a dialog box. 


You create document windows from a window resource using the function 

Get NewCWindow or Get NewWindow. (Whenever Color QuickDraw is available, use 
GetNewCWindow to create color windows, whether or not a color monitor is currently 
installed. A color window record is the same size as a window record, and 
GetNewCWindow returns a pointer of type WindowPtr, so most code can handle color 
windows and monochrome windows identically.) 


You can allow Get NewCWindow to allocate the memory for your window record. You 

can maintain more control over memory use, however, by allocating the memory 
yourself from a block allocated for such purposes during your own initialization routine, 
and then passing the pointer to GetNewCWindow. 


You typically create the scroll bars from control ('CNTL') resources at the time that you 
create a document window and then display them when you make the window visible. 


Using the Window Manager 4-27 


CHAPTER 4 


Window Manager 


Listing 4-3 illustrates an application-defined procedure, DoNewCmd, which SurfWriter 
calls when the user chooses New from the File menu. Windows are typically invisible 
when created and displayed only after all elements are in place. 


Listing 4-3 Creating a new window 


PROCEDURE DoNewCmd (newDocument: Boolean; VAR window: WindowPtr); 
VAR 


myData: MyDocRecHnd; {the document's data record} 
windStorage: REL; {memory for window record} 
destRect, {rectangles for creating } 
viewRect: Rect; { TextEdit edit record} 
good: Boolean; {success flag} 


BEGIN 
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window := NIL; {no window created yet} 
good := FALSE; {no success yet} 
{allocate memory for window record from previously allocated block} 
windStorage := MyPtrAllocationProc; 
IF windStorage <> NIL THEN {memory allocation succeeded} 
BEGIN {create window} 
IF gColorQDAvailable THEN 
window := GetNewCWindow(rDocWindow, windStorage, WindowPtr(-1) ) 
ELSE 
window := GetNewWindow(rDocWindow, windStorage, WindowPtr(-1)); 
END; 
{create document record} 
myData := MyDocRecHnd (NewHandle (SIZEOF (MyDocRec) )); 
IF (window <> NIL) AND (myData <> NIL) THEN {window record and document } 
BEGIN { record both allocated} 
SetPort (window) ; {set current port} 
HLock (Handle (myData) ); {lock handle to doc record} 
SetWRefCon (window, LongInt (myData) ); {link document record to window} 
WITH window’, myData** DO {fill in document record} 
BEGIN 
MyGetTERect (window, viewRect); {set up a viewRect for TextEdit} 
destRect := viewRect; 
destRect.right := destRect.left + kMaxDocWidth; 
editRec := TENew(destRect, viewRect); 
IF editRec <> NIL THEN {it's a good edit record} 
BEGIN 
good := TRUE; {set success flag} 
MyAdjustViewRect (editRec) ; {set up edit record} 
TEAutoView (TRUE, editRec); 
END 
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ELSE 
good := FALSE; {clear success flag} 
IF good THEN 
BEGIN {create scroll bars} 
vScrollBar := GetNewControl(rVScroll, window) ; 
hScrollBar := GetNewControl(rHScroll, window); 
good := (vScrollBar <> NIL) AND (hScrollBar <> NIL); 
END; 
IF good THEN {it's a good document } 
BEGIN 
MyAdjustScrollBars (window, FALSE); {adjust scroll bars} 
fileRefNum := 0; {no file yet} 
windowDirty := FALSE; {no changes yet} 
IF newDocument THEN {if it's a new (empty) document, } 
ShowWindow (window) ; { make it visible} 
END; 
END; {end of WITH statement} 
HUnlock (Handle (myData) ); {unlock document record} 
END; {end of IF (window <> NIL) AND (myData <> NIL) } 
IF NOT good THEN 
BEGIN 
IF windStorage <> NIL THEN {memory for window record was allocated} 
DisposePtr(windStorage); {dispose of it} 
IF myData <> NIL THEN {memory for document record was allocated} 
BEGIN 
IF myData**.editRec <> NIL THEN {edit record was allocated} 
TEDispose(myData**.editRec); {dispose of it} 
DisposeHandle (Handle (myData) ); {dispose of document record} 
END; 
IF window <> NIL THEN {window pointer exists, but it's invalid} 
CloseWindow (window) ; {clean up window pointer} 
window := NIL; {set window to NIL to indicate failure} 


END; 
END; {DoNewCmd} 


The DoNewCmd procedure first sets the window pointer and success flags to show 

that a valid window doesn’t yet exist. Then it calls the application-defined function 
MyPtrAllocationProc, which allocates memory for a window record from a block 
set aside during program initialization for that purpose. If MyPt rAllocationProc 
successfully allocates memory and returns a valid pointer, DoNewCmd creates a window, 
specifying the 'WIND' resource with resource ID 128, as specified by the constant 
rDocWindow. Using this window resource (defined in Listing 4-2 on page 4-26), the 
Window Manager creates an invisible window of type zoomDocProc. Because 

the behind parameter to Get NewCWindow or Get NewWindow has the value 
WindowPtr (-1), the Window Manager places the new window in front of all others 
on the desktop. 
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The DoNewCmd procedure then creates a document record. It locks the document record 

in memory while manipulating it, sets the refCon field in the window record so that it 
points to the document record, and fills in the document record. While filling in the 
document record, DoNewCmd sets up a TextEdit record to hold the user’s data. If that 
succeeds, DoNewCmd sets up horizontal and vertical scroll bars. If that succeeds, 
DoNewCmd adjusts the scroll bars (see the chapter “Control Manager” in this book for the 
application-defined procedure MyAdjustScrollbars) and fills in the remaining parts 
of the document record. If the window is being created to display a new document, that 
is, if no user data needs to be read from a disk, DoNewCmd calls the ShowWindow 
procedure to make the window visible immediately. 


If your window resource specifies that a new window is visible, GetNewCWindow 
displays the window immediately. If you're creating a document window, however, 
you're more likely to create the window in an invisible state and then make it visible 
when you're ready to display it. 


m If you're creating a window because the user is creating a new document, you can 
display the window immediately by calling the procedure ShowWindow to make the 
window frame visible. This change in visibility adds to the update region and triggers 
an update event. Your application then invokes its own procedure for drawing the 
content region in response to the update event. 


m If you’re creating a new window to display a saved document, you must retrieve the 
user’s data before displaying it. (See Inside Macintosh: Files for information about 
reading saved files.) If possible, the size and location of the window that displays the 
document should be the same as when the document was last saved. (See the next 
section, “Positioning a Document Window on the Desktop,” for a discussion of 
window placement.) Once you have positioned the window and set up its content 
region, you can make the window visible by calling ShowWindow, which triggers an 
update event. Your application then invokes its own procedure for drawing the 
content region. 


Positioning a Document Window on the Desktop 


Your goal in positioning a window on the desktop is to place it where the user expects it. 
For a new document, this usually means just below and to the right of the last document 
window in which the user was working. For a saved document, it usually means the 
location of the document window when the document was last saved (if it was saved on 
a computer with the same screen configuration). This section describes the placement of 
document windows. The chapter “Dialog Manager” in this book describes the placement 
of alert boxes and dialog boxes. See Macintosh Human Interface Guidelines for a complete 
description of window placement. 


On Macintosh computers with a single screen of known size, positioning windows 

is fairly straightforward. You position the first new document window on the upper-left 
corner of the desktop. Open each additional new document window with its upper- 

left corner slightly below and to the right of the upper-left corner of its predecessor. 
Figure 4-15 illustrates how to position multiple documents on a single screen. 
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Figure 4-15 Document window positions on a single screen 
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If the user closes one or more document windows, display subsequent windows in the 
“empty” positions before adding more positions below and to the right. Figure 4-16 
illustrates how you fill in an empty position when the user opens a new document after 
closing one created earlier. 


Figure 4-16 “Filling in” an empty document window position 
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On computers with multiple monitors, window placement depends on a number 
of factors: 


gm the number of screens available and their dimensions 
gm the location of the main screen—that is, the screen that contains the menu bar 
m the location of the screen on which the user was most recently working 


In general, you place the first new document window on the main screen, and you place 
subsequent document windows on the screen that contains the largest portion of the 
most recently active document window. That is, if you display a blank document 
window when the user starts up your application, you place the window on the main 
screen. If the user moves the window to another screen and then creates another new 
document, you place the new document window on the other screen. Although the user 
is free to place windows so that they cross screen boundaries, you should never display a 
new window that spans multiple screens. 


When the user opens a saved document, you replicate the size and location of the 
window in which the document was last saved, if possible. 


The Window Manager recognizes a set of positioning constants in the window 
resource that let you position new windows automatically. You typically use the 
constant staggerParentWindowScreen for positioning document windows. The 
staggerParentWindowScreen constant specifies the basic guidelines for document 
window placement: When creating windows from a template that includes 
staggerParentWindowScreen, the Window Manager places the first window in 
the upper-left corner of the main screen. It places subsequent windows with their 
upper-left corners 20 pixels to the right and 20 pixels below the upper-left corner 

of the last window in which the user was working. Figure 4-17 illustrates how 

the Window Manager positions a new document window when the 
staggerParentWindowScreen specification is in effect and the user has been 
working in a window off the main screen. 


If the user moves or closes a window that occupies one of the interim positions, and the 
window template specifies staggerParentWindowScreen, the Window Manager 
uses the “empty” slot for the next new window created before moving further down and 
to the right. 


For a complete list of the positioning constants and their effects, see “The Window 
Resource” beginning on page 4-124. 


You can usually use the staggerParentWindowScreen positioning constant when 
creating a window that is to display a new document. You must perform your own 
window-placement calculations, however, when opening saved documents and when 
zooming windows. 


When the user saves a document, the document window can be in one of two states: the 
user state or the standard state. 
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Figure 4-17 Document window positions on multiple screens 
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The user state is the last size and location the user established for the window. 


The standard state is what your application determines is the most convenient size for 
the window, considering the function of the document and the screen space available. 
For a more complete description of the standard state, see “Zooming a Window” 
beginning on page 4-53. Your application typically calculates the standard state each 
time the user zooms to that state. 


The user and standard states are stored in the state data record, whose handle appears in 
the dataHandle field of the window record. 


TYPE WStateData = 














RECORD 
userState: Rect; {size and location established by user} 
stdState: Rect; {size and location established by } 
{ application} 
END; 


When the user saves a document, you must save the user state rectangle and the state of 
the window (that is, whether the window is in the user state or the standard state). Then, 
when the user opens the document again later, you can replicate the window’s status. 
You typically store the state data as a resource in the resource fork of the document file. 
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Listing 4-4 illustrates an application-defined data structure for storing the window’s user 


rectangle and state. 


Listing 4-4 Application-defined data structure for storing a window’s state data 





TYPE MyWindowState = 


RECORD 
userStateRect: Rect; {user state rectangle} 
zoomState: Boolean; {window state: TRUE = standard; 
{ FALSE = user} 
END; 
MyWindowStatePtr = “MyWindowState; 


MyWindowStateHnd = “MyWindowStatePtr; 


This structure translates into an application-defined resource that is stored in the 
resource fork of the document when the user saves the document. 


Listing 4-5 shows an application-defined routine for saving a document's state data. 


saves a document. 


Listing 4-5 Saving a document window’s position 


PROCEDURE MySaveWindowPosition (myWindow: WindowPtr; 
myResFileRefNum: Integer); 


VAR 
lastWindowState: MyWindowState; 
myStateHandle: MyWindowStateHnd; 
curResRefNum: Integer; 

BEGIN 
{Set user state provisionally and determine whether window is zoomed. } 
lastWindowState.userStateRect := WindowPeek (myWindow) *.contRgn**.rgnBBox; 
lastWindowState.zoomState := EqualRect (lastWindowState.userStateRect, 





MyGetWindowStdState (myWindow) ) 


} 


The 
SurfWriter application calls the procedure MySaveWindowPosition when the user 


, 


{if window is in standard state, then set the window's user state from } 





{ the userState field in the state data record} 











IF lastWindowState.zoomState THEN {window was in standard state} 
lastWindowState.userStateRect := MyGetWindowUserState (myWindow) ; 
curResRefNum := CurResFile; {save the refNum of current resource file} 





UseResFile (myResFileRefNum) ; {set the current resource file} 
myStateHandle := MyWindowStateHnd (Get1Resource (rWinState, 
kLastWinStatelID) ); 
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IF myStateHandle <> NIL THEN {a state data resource already exists} 
BEGIN {update it} 
myStateHandle** := lastWindowState; 
ChangedResource (Handle (myStateHandle) ); 
END 
ELSE {no state data has yet been saved} 
BEGIN {add state data resource} 
myStateHandle := MyWindowStateHnd (NewHandle (SizeOf (MyWindowState) )); 
IF myStateHandle <> NIL THEN 
BEGIN 
myStateHandle** := lastWindowState; 


AddResource (Handle (myStateHandle), rWinState, kLastWinStatelID, 
‘last window state'); 





IF myStateHandle <> NIL THEN 
BEGIN 
UpdateResFile (myResFileRefNum) ; 
ReleaseResource (Handle (myStateHandle) ); 
END; 
UseResFile (curResRefNum) ; 
END; 











The MySaveWindowPosition procedure first determines whether the window is in the 
user state or the standard state by setting its own user state field from the bounding 
rectangle of the window’s content region and comparing that rectangle with the user 
state stored in the state data record. (If the two match, the window is in the user state; if 
not, the standard state.) If the window is in the standard state, the procedure replaces its 
own user state data with the rectangle stored in the userState field of the state data 
record. The rest of the procedure saves the application-defined state data record in the 
resource fork of the document. 


When creating a new window to display a saved document, SurfWriter restores the 
saved user state data and recalculates the standard state. Before using the saved 
rectangle, however, SurfWriter verifies that the location is reachable on the desktop. (If 
the user saves a document on a computer equipped with multiple monitors and then 
opens it later on a system with only one monitor, for example, the saved window 
location could be entirely or partially off the screen.) 


Listing 4-6 on the next page shows MySetWindowPosition, the application- 
defined routine that SurfWriter calls when the user opens a saved document. The 
MySetWindowPosition procedure retrieves the document’s saved state data and 
then calls another application- defined routine, MyVerifyPosition, to verify 
that the saved location is practical. 
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Listing 4-6 Positioning the window when the user opens a saved document 


PROCEDURE MySetWindowPosition (myWindow: WindowPtr) ; 


VAR 
myData: MyDocRecHnd; 
lastUserStateRect: Rect; 
stdStateRect: Rect; 
curStateRect: Rect; 
myRefNum: Integer; 
myStateHandle: MyWindowStateHnd; 
resourceGood: Boolean; 
savePort: GrafPtr; 
myErr: OSErr; 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (myWindow) ) ; {get document record} 
HLock (Handle (myData) ); {lock the record while manipulating it} 
{open the resource fork and get its file reference number} 
myRefNum := FSpOpenResFile(myData**.fileFSSpec, fsRdWrPerm) ; 
myErr := ReskError; 
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IF myErr <> noErr THEN 
Exit (MySetWindowPosition) ; 


{get handle to rectangle that describes document's last window position} 








myStateHandle := MyWindowStateHnd (Get1Resource (rWinState, 
kLastWinStatelID) ); 
IF myStateHandle <> NIL THEN {handle to data succeeded} 
BEGIN {retrieve the saved user state} 
lastUserStateRect := myStateHandle**.userStateRect; 
resourceGood := TRUE; 
END 
ELSE 
BEGIN 
lastUserStateRect.top := 0; {force MyVerifyPosition to calculate } 
resourceGood := FALSE; { the default position} 
END; 


{verify that user state is practical and calculate new standard state} 
MyVerifyPosition(myWindow, lastUserStateRect, stdStateRect); 


IF resourceGood THEN {document had state resource} 
IF myStateHandle**.zoomState THEN {if window was in standard state } 
curStateRect := stdStateRect { when saved, display it in } 
{ newly calculated standard state} 
ELSE {otherwise, current state is the user state} 
curStateRect := lastUserStateRect 
ELSE {document had no state resource} 
curStateRect := lastUserStateRect; {use default user state} 
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{move window} 

MoveWindow(myWindow, curStateRect.left, curStateRect.top, FALSE); 
{Convert to local coordinates and resize window. } 

GetPort (savePort) ; 

SetPort (myWindow) ; 

GlobalToLocal (curStateRect.topLeft) ; 

GlobalToLocal (curStateRect .botRight) ; 

SizeWindow(myWindow, curStateRect.right, curStateRect.bottom, TRU 





Gl 
~~ 
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IF resourceGood THEN {reset user state and standard } 

BEGIN { state--SizeWindow may have changed them} 
MySetWindowUserState(myWindow, lastUserStateRect) ; 
MySetWindowStdState (myWindow, stdStateRect) ; 

END; 

ReleaseResource (Handle (myStateHandle) ); {clean up} 

CloseResFile (myRefNum) ; 

HUnLock (Handle (myData) ); 

END; 








The MyVerifyPosition routine, not shown here, compares the saved location against 
available screen space. (See Listing 4-12 on page 4-55 for a strategy for comparing the 
saved rectangle with the available screen space.) MyVerifyPosition alters the user 
state rectangle, if necessary (using the same size, if possible, but placing it on available 
screen space) and calculates a new standard state for displaying the window on the 
screen containing the user state. 


After determining valid user and standard state rectangles, the procedure 
MySetWindowPosition sets a temporary positioning rectangle to the appropriate 
size and location, based on the state of the document’s window when the document 
was saved. The MySetWindowPosition procedure then calls the Window Manager 
procedures MoveWindow and SizeWindow to establish the window’s location and 
size before cleaning up. 


The SurfWriter application calls MySetWindowPosition from its routine for opening 
saved documents, after reading the document’s data from its data fork. Listing 4-7 shows 
the application-defined DoOpenFile function that SurfWriter calls when the user opens 
a saved document. 


Listing 4-7 Opening a saved document 


FUNCTION DoOpenFile (mySpec: FSSpec): OSErr; 
VAR 

myWindow: WindowPtr; 

myData: MyDocRecHnd; 

myFileRefNum: Integer; 

myErr: OSErr; 
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BEGIN 
DoNewCmd (FALSE, myWindow) ; {FALSE tells DoNewCmd not to } 
{ show the window} 
IF myWindow = NIL THEN 
BEGIN 
DoOpenFile := kOpenFileError; 





Exit (DoOpenFile) ; 

END; 

SetWTitle(myWindow, mySpec.name) ; 

{open the file's data fork, passing the file spec-—— } 





{ FSpOpenDF returns a file reference number} 

myErr := FSpOpenDF (mySpec, fsRdWrPerm, myFileRefNum) ; 

IF (myErr <> noErr) AND (myErr <> opWrErr) THEN {open failed} 

BEGIN {clean up} 
DisposeWindow (myWindow) ; 








DoOpenFile := myErr; 
Exit (DoOpenFile) ; 
END; 
{get a handle to the window's document record} 


myData := MyDocRecHnd (GetWRefCon (myWindow) ) ; 
myData®**.fileRefNum := myFileRefNum; {save file ref num} 
myData**.fileFSSpec := mySpec; {save fsspec} 

myErr := DoReadFile (myWindow) ; {read file's data} 


{retrieve saved state data and establish valid position} 
MySetWindowPosition (myWindow) ; 
{MyResizeWindow invalidates the whole portRgn, guaranteeing } 
{ an update event-—-the window's contents are redrawn then} 
MyResizeWindow (myWindow) ; 
ShowWindow (myWindow) ; {show window} 
DoOpenFile := myErr; 

END; 


DoOpenFile first calls the application-defined procedure DoNewCmd to create a new 
window, suppressing the immediate display of the window. (Listing 4-3 on page 

page 4-28 illustrates the procedure DoNewCmd.) Then DoOpenFile sets the window 
title to the name of the document file and reads in the data. Then it calls 
MySetWindowPosition to determine where to place the new window. After 
establishing a valid position, DoOpenFile calls the application-defined routine 
MyResizeWindow (shown in Listing 4-14 on page 4-59) to set up the content region 

in the new dimensions, and then it finally makes the window visible. 


Using the Window Manager 


CHAPTER 4 


Window Manager 


Drawing the Window Contents 


Your application and the Window Manager work together to display windows on the 
screen. Once you have created a window and made it visible, the Window Manager 
automatically draws the window frame in the appropriate location. As the user makes 
changes to the desktop, moving and resizing different windows, the Window Manager 
alters the window frames as necessary. The window frame includes the window outline, 
the title bar, and the close and zoom boxes. 


Your application is responsible for drawing the window’s content region. It typically 
uses the Control Manager to draw the window controls, uses the Window Manager to 
draw the size box, and draws the user data itself. The sample code in this chapter uses 
the simple model of a content region that contains only controls, the size box, and a 
TextEdit record. (See Inside Macintosh: Text for a description of TextEdit.) 


Listing 4-8 illustrates an application-defined procedure that draws the content region of 
a window. 


Listing 4-8 Drawing a window 


PROCEDURE MyDrawWindow (window: WindowPtr); 
VAR 
myData: MyDocRecHnd; 
BEGIN 
SetPort (window) ; 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
WITH window’ DO 
BEGIN 
EraseRect (portRect) ; {erase content area} 














UpdateControls (window, visRgn); {draw window controls} 





DrawGrowlcon (window) ; {draw size box} 


{update window contents as appropriate to your } 





{ application (in this case use TextEdit) } 





TEUpdate (portRect, myData**.editRec) ; 
END; 
HUnLock (Handle (myData) ); 

END; 


The MyDrawWindow procedure first sets the current port to the window’s port and gets a 
handle to the window’s document record. Using the data in the document record, the 
procedure first erases the content region, draws the controls, and draws the size box. 
Finally, it draws the user’s data, in this case the contents of a TextEdit edit record. 


Using the Window Manager 4-39 


CHAPTER 4 


Window Manager 


If your application creates a window that contains a static display, you can let the 
Window Manager take care of drawing and updating the content region by placing a 
handle to a picture in the windowPic field of the window record. See the description 
of the SetWindowPic procedure on page 4-110. 


Updating the Content Region 


The Window Manager helps your application keep the window display current by 
maintaining an update region, which represents the parts of your content region 

that have been affected by changes to the desktop. If a user exposes part of an inactive 
window by dragging an active window to a new location, for example, the Window 
Manager adds the newly exposed area of the inactive window to that window’s 
update region. 


Figure 4-18 illustrates how the Window Manager adds part of a window’s content region 
to its update region when the user exposes additional content area. 


Figure 4-18 Moving one window and adding to another window’s update region 
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The Event Manager periodically scans the update regions of all windows on the desktop. 
If it finds one whose update region is not empty, it generates an update event for that 
window. When your application receives an update event, it redraws as much of the 
content area as necessary, as described in the section “Handling Update Events” 
beginning on page 4-48. 


As the user makes changes to a document, your application must update both the 
document data and the document display in the content area of its window. You can 
use one of two strategies for updating the display: 


m If your application doesn’t require continuous scrolling or rapid response, you can 
add changed areas of the content region to the window’s update region. The Event 
Manager then sends your application an update event, and your application invokes 
its standard update procedure. 


a For continuous scrolling and a faster response time, you can draw directly into the 
content area of the window. 


In either case, your application ultimately draws in the graphics port that represents 
the window. You draw controls through the Control Manager, and you draw text 

and graphics with the routines described in Inside Macintosh: Text and Inside Macintosh: 
Imaging. 


Maintaining the Update Region 


Your application can force and suppress update events by manipulating the update 
region, using Window Manager routines provided for this purpose. 


Your application usually manipulates the update region, for example, when the user 
resizes a window that contains a size box and scroll bars. If the user enlarges the 
window, the Window Manager adds the newly exposed area to the window’s update 
region but does not add the area formerly occupied by the scroll bars. Before calling the 
SizeWindow procedure to resize the window, your application can call the InvalRect 
procedure twice to add the scroll bar and size box areas to the update region. The next 
time it receives an update event, your application erases the scroll bars and draws 
whatever parts of the document content might be visible at that location. 


Similarly, you can remove an area from the update region when you know that it is in 
fact valid. Limiting the size of the update region decreases time spent redrawing. Listing 
4-13 on page 4-58, for example, uses the ValidRect procedure to remove the unaffected 
text area from the update region of a window that is being resized. 


Handling Events in Windows 
Your application must be prepared to handle two kinds of window-related events: 


m= mouse and keyboard events in your application’s windows, which are reported by the 
Event Manager in direct response to user actions 


m activate and update events, which are generated by the Window Manager and the 
Event Manager as an indirect result of user actions 
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In System 7 your application receives mouse-down events if it is the foreground process 
and the user clicks in the menu bar, a window belonging to your application, or a 
window belonging to a desk accessory that was launched in your application’s partition. 
(If the user clicks in a window belonging to another application, the Event Manager 
sends your application a suspend event and performs a major switch to the other 
application—unless the frontmost window is an alert box or a modal dialog box, in 
which case the Dialog Manager merely sounds the system alert, and the Process 
Manager retains your application as the foreground process.) When it receives a 
mouse-down event, your application first calls the FindWindow function to map the 
cursor location to a window region, and then it branches to one of its own routines, as 
described in the next section, “Handling Mouse Events in Windows.” 


The Event Manager sends your application an update event when changes on the 
desktop or in a window require that part or all of a window’s content region be updated. 
The Window Manager and your application can both trigger update events by adding 
regions that need updating to the update region, as described in the section “Handling 
Update Events” beginning on page 4-48. 


Your application receives activate events when an inactive window becomes active or an 
active window becomes inactive. Activate events are an example of the close cooperation 
between your application and the Window Manager. When you receive a mouse-down 
event in one of your application’s inactive windows, you can call the SelectWindow 
procedure, which removes the highlighting from the previously active window and adds 
highlighting to the newly active window. It also generates two activate events: one 
telling your application to deactivate the previously active window and one to activate 
the newly active window. Your application then activates and deactivates the content 
regions, as described in the section “Handling Activate Events” beginning on page 4-50. 


When the user first clicks in an inactive window, most applications do not make a 
selection or otherwise change the window or document, beyond making the window 
active. When your application receives a resume event because the user clicked in one of 
its windows, you might not even want to receive the mouse-down event that caused 
your application to become the foreground process. You control whether or not you 
receive this event through the 'SIZE' resource, described in the chapter “Event 
Manager” earlier in this book. 





Handling Mouse Events in Windows 


When your application is active, it receives notice of all keyboard activity and 
mouse-down events in the menu bar, in one of its windows, or in any windows 
belonging to desk accessories that were launched in its partition. 


When it receives a mouse-down event, your application calls the FindWindow function 
to map the cursor location to a window region. 


The function specifies the region by returning one of these constants: 


CONST inDesk = 0; {none of the following} 


inMenuBar Snilhe {in menu bar} 





inSysWindow = 2; {in desk accessory window} 
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inContent = 3; {anywhere in content region except size } 





{ box if window is active, } 
{ anywhere including size box if window } 


{ is inactive} 


inDrag = 4; {in drag (title bar) region} 

inGrow = 15} {in size box (active window only) } 
inGoAway = 6; {in close box} 

inZoomIn = 7; {in zoom box (window in standard state) } 
inZoomOut = 8; {in zoom box (window in user state) } 


When the user presses the mouse button while the cursor is in a window, FindWindow 
not only returns a constant that identifies the window region but also sets a variable 
parameter that points to the window. 


In System 7, if FindWindow returns inDesk, the cursor is somewhere other than in the 
menu bar, one of your windows, or a window created by a desk accessory launched in 
your application’s partition. The function may return inDesk if, for example, the cursor 
is in the window frame but not in the drag region, close box, or zoom box. FindWindow 
seldom returns the value inDesk, and you can generally ignore the rare instances of this 
function result. 


If the user presses the mouse button with the cursor in the menu bar (inMenuBar), 
you call your own routines for displaying menus and allowing the user to choose 
menu items. 


The FindWindow function returns the value inSysWindow only when the user presses 
the mouse button with the cursor in a window that belongs to a desk accessory launched 
in your application’s partition. You can then call the SystemClick procedure, passing it 
the event record and window pointer. The SystemClick procedure, documented in the 
chapter “Event Manager” in this book, makes sure that the event is handled by the 
appropriate desk accessory. 


The FindWindow function returns one of the other values when the user presses 
the mouse button while the cursor is in one of your application’s windows. Your 
response depends on whether the cursor is in the active window and, if not, what 
kind of window is active. 


When you receive a mouse-down event in the active window, you route the event to the 
appropriate routine for changing the window display or the document contents. When 
the user presses the mouse button while the cursor is in the zoom box, for example, you 
call the Window Manager function TrackBox to highlight the zoom box and track the 
mouse until the button is released. 


When you receive a mouse-down event in an inactive window, your response depends 
on what kind of window is active: 


m Ifthe active window is a movable modal dialog box, you should sound the system 
alert and take no other action. (If the active window is a modal dialog box handled by 
the ModalDialog procedure, the Dialog Manager doesn’t pass the event to your 
application but sounds the system alert itself.) 
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m Ifthe active window is a document window or a modeless dialog box, you can call 
SelectWindow, passing it the window pointer. The Select Window procedure 
removes highlighting from the previously active window, brings the newly activated 
window to the front, highlights it, and generates the activate and update events 
necessary to tell all affected applications which windows must be redrawn. 


Listing 4-9 illustrates an application-defined procedure that handles mouse-down events. 


Listing 4-9 Handling mouse-down events 


PROCEDURE DoMouseDown (event: EventRecord) ; 
VAR 
part: Integer; 
thisWindow: WindowPtr; 
BEGIN 
part := FindWindow(event.where, thisWindow); {find out where cursor is} 
CASE part OF 
inMenuBar: {cursor is in menu bar} 
BEGIN 
{make sure menu items are properly enabled/disabled} 








MyAdjustMenus; 
{let user choose a menu command} 





DoMenuCommand (MenuSelect (event.where) ); 
END; 
inSysWindow: {cursor is in a desk accessory window} 
SystemClick (event, thisWindow) ; 
inContent: {cursor is in the content region of one } 
{ of your application's windows} 
IF thisWindow <> FrontWindow THEN {cursor is not in front window} 
BEGIN 
IF MyIsMovableModal (FrontWindow) THEN {front window is } 
SysBeep (30) { movable modal} 
ELSE {front window is not movable modal} 
SelectWindow (thisWindow) ; {make thisWindow active} 
END 
ELSE {cursor is in content region of active window} 
DoContentClick (thisWindow, event); {handle event in content region} 
inDrag: {cursor is in drag area} 
{if a movable modal is active, ignore click in an inactive title bar} 
IF (thisWindow <> FrontWindow) AND MyIsMovableModal (FrontWindow) THEN 
SysBeep (30) 
ELSE 
{let Window Manager drag window} 
DragWindow(thisWindow, event.where, GetGrayRgn**.rgnBBox) ; 





inGrow: {cursor is in size box} 
DoGrowWindow(thisWindow, event); {change window size} 
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inGoAway: {cursor is in close box} 
{call TrackGoAway to handle mouse until button is released} 





IF TrackGoAway (thisWindow, event.where) THEN 
DoCloseCmd; {handle close window} 
inZoomIn, inZoomOut: {cursor is in zoom box} 
{call TrackBox to handle mouse until button is released} 
IF TrackBox(thisWindow, event.where, part) THEN 
DoZoomWindow(thisWindow, part); {handle zoom window} 
END; {end of CASE statement} 








END; {end of DoMouseDownEvent } 


The DoMouseDown procedure first calls FindWindow to map the location of the cursor 
to a part of the screen or a region of a window. 


If the cursor is in the menu bar, DoMouseDown calls other application-defined 
procedures for adjusting and displaying menus and accepting menu choices. 


If the cursor is in a window created by a desk accessory, DoMouseDown calls the 
SystemClick procedure, which handles mouse-down events for desk accessories from 
within applications. 


If the cursor is in the content area of a window, DoMouseDown first checks to see 
whether the cursor is in the currently active window by comparing the window pointer 
returned by FindWindow with the result returned by the function FrontWindow. If 
the cursor is in an inactive window, DoMouseDown checks to see if the active window 
is a movable modal dialog box. (If the front window is an alert box or a fixed-position 
modal dialog box, an application does not receive mouse-down events in other 
windows.) If the active window is a movable modal dialog box and the cursor is in 
another window, DoMouseDown simply sounds the system alert and waits for another 
event. If the active window is not a movable modal dialog box, DoMouseDown 

calls SelectWindow to activate the window in which the cursor is located. The 
SelectWindow procedure relayers the windows as necessary, adjusts the highlighting, 
and sends the application a pair of activate events to deactivate the previously active 
window and activate the newly active window. DoMouseDown merely activates 

the window in which the cursor is located; it does not make a selection in the newly 
activated window in response to the first click in that window. 


If the cursor is in the content area of the active window, the DoMouseDown procedure 
calls another application-defined procedure (DoContentClick) that handles mouse 
events in the content area. 


If the cursor is in the drag region of a window, DoMouseDown first checks whether the 
drag region is in an inactive window while a movable modal dialog box is active. In 

that case, DoMouseDown merely sounds the system alert and waits for another event. In 
any other case, DoMouseDown calls the Window Manager procedure DragWindow, 
which displays an outline of the window, moves the outline as long as the user continues 
to drag the window, and calls MoveWindow to draw the window in its new location 
when the user releases the mouse button. After the window is drawn in its new location, 
it is the active window, whether or not it was active before. 
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If the cursor is in the size box, DoMouseDown calls another application-defined routine 
(DoGrowWindow, shown in Listing 4-13 on page 4-58) that resizes the window. 


If the mouse press occurs in the close box, DoMouseDown calls the TrackGoAway 
function, which highlights the close box and tracks all mouse activity until the user 
releases the mouse button. As long as the user holds down the mouse button and leaves 
the cursor in the close box, TrackGoAway leaves the close box highlighted, as illustrated 
in Figure 4-19. If the user moves the cursor out of the close box, TrackGoAway removes 
the highlighting. 


Figure 4-19 The close box with and without highlighting 
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When the user releases the mouse button, TrackGoAway returns TRUE if the 
cursor is still in the close box and FALSE if it is not. If TrackGoAway returns TRUE, 
DoMouseDown calls the application-defined procedure DoCloseCmd to close the 
window. Listing 4-16 on page 4-60 shows the DoCloseCmd procedure. 








If the mouse press occurs in the zoom box, the DoMouseDown procedure first calls 
TrackBox, which highlights the zoom box and tracks all mouse activity until the user 
releases the mouse button. As long as the user holds down the mouse button and leaves 
the cursor in the zoom box, TrackBox leaves the zoom box highlighted, as illustrated in 
Figure 4-20. If the user moves the cursor out of the zoom box, TrackBox removes the 
highlighting. 








When the user releases the mouse button, TrackBox returns TRUE if the cursor is still in 
the zoom box and FALSE if it is not. If TrackBox returns TRUE, DoMouseDown calls the 
application-defined procedure DoZoomWindow to zoom the window. Listing 4-12 on 
page 4-55 shows the DoZoomWindow procedure. 
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Figure 4-20 The zoom box with and without highlighting 
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Handling Keyboard Events in Windows 


Whenever your application is the foreground process, it receives key-down events 

for all keyboard activity, except for the three standard Command-Shift-number key 
sequences and any other Command-Shift-number key combinations the user has 
installed. (Command-Shift-1 and Command-Shift-2 eject disks, and Command-Shift-3 
stores a snapshot of the screen in a TeachText document on the startup volume. Your 
application never receives these key combinations, which are handled by the Event 
Manager. For more information, see the chapter “Event Manager” in this book.) 


In general, the active window is the target of keyboard activity. 


When the user presses a key or a combination of keys, your application responds by 
inserting data into the document, changing the display, or taking other actions as defined 
by your application. To ensure consistent use of and response to keyboard events, follow 
the guidelines in Macintosh Human Interface Guidelines. Your application should, for 
example, allow the user to choose frequently used menu items by pressing a keyboard 
equivalent—usually a combination of the Command key and another key. 


When you receive a key-down event, you first check whether the user is holding down 
a modifier key (Command, Shift, Control, Caps Lock, and Option, on a standard 
keyboard) and another key at the same time. If the Command key and a character key 
are held down simultaneously, for example, you adjust your menus, enabling and 
disabling items as appropriate, and allow the user to choose the menu item associated 
with the Command-key combination. 


Typically, your application provides feedback for standard keystrokes by drawing the 
character on the screen. It should also recognize arrow keys for moving the cursor within 
a text display, and it might add support for function keys or other special keys available 
on nonstandard keyboards. 


For an example of an application-defined routine for handling keyboard events, see the 
chapter “Event Manager” in this book. 
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Handling Update Events 


The Event Manager sends your application an update event when part or all of your 
window’s content region needs to be redrawn. Specifically, the Event Manager checks 
each window’s update region every time your application calls WaitNextEvent or 
EventAvail (or GetNextEvent) and generates an update event for every window 
whose update region is not empty. 


The Window Manager typically triggers update events when the moving and relayering 
of windows on the screen require that one or more windows be redrawn. If the user 
moves a window that covers part of an inactive window, for example, the Window 
Manager first calls the window definition function of the inactive window, requesting 
that it draw the window frame. It then adds the newly exposed area to the window’s 
update region, which triggers an update event asking your application to update the 
content region. Your application can also trigger update events itself by manipulating the 
update region. 


Your application can receive update events when it is in either the foreground or 
the background. 


The Window Manager ensures that you do not accidentally draw in other windows by 
clipping all screen drawing to the visible region of a window’s graphics port. The visible 
region is the part of the graphics port that’s actually visible on the screen—that is, the 
part that’s not covered by other windows. The Window Manager stores a handle to the 
visible region in the visRgn field of the graphics port data structure, which itself is in 
the window record. 





In response to an update event, your application calls the BeginUpdate procedure, 
draws the window’s contents, and then calls the EndUpdate procedure. As illustrated 
in Figure 4-21, BeginUpdate limits the visible region to the intersection of the visible 
region and the update region. Your application can then update either the visible region 
or the entire content region—because QuickDraw limits drawing to the visible region, 
only the parts of the window that actually need updating are drawn. The BeginUpdate 
procedure also clears the update region. After you’ve updated the window, you call 
EndUpdate to restore the visible region in the graphics port to the full visible region. 








See Inside Macintosh: Imaging for more information about graphics ports and 
visible regions. 
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Figure 4-21 The effects of BeginUpdate and EndUpdate on the visible region and 
update region 
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Listing 4-10 illustrates an application-defined procedure, DoUpdate, that handles 
an update event. 


Listing 4-10 Handling update events 


PROCEDURE DoUpdate (window: WindowPtr); 








VAR 
windowType: LongInt; 
BEGIN 
{determine type of window as defined by this application} 
windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: {document window} 
BEGIN 





BeginUpdate (window) ; 
MyDrawWindow (window) ; 





EndUpdate (window) ; 
END; 
OTHERWISE {alert or dialog box} 
DoUpdateMyDialog (window) ; 
END; {of CASE} 














END; 


The DoUpdate procedure first determines whether the window being updated is a 
document window or some other application-defined window by calling the 
application-defined procedure MyGetWindowType (shown in Listing 4-1 on 

page 4-25). If the window is a document window, DoUpdate calls BeginUpdate 
to establish the temporary visible region, calls the application-defined procedure 
MyDrawWindow (shown in Listing 4-8 on page 4-39) to redraw the content region, 
and then calls EndUpdate to restore the visible region. 


If the window is an alert box or a dialog box, DoUpdate calls the application-defined 
procedure DoUpdat eMyDialog, which is not shown here. 


Handling Activate Events 


Your application activates and deactivates windows in response to activate events, 
which are generated by the Window Manager to inform your application that a window 
is becoming active or inactive. Each activate event specifies the window to be changed 
and the direction of the change (that is, whether it is to be activated or deactivated). 


Your application often triggers activate events itself by calling the SelectWindow 
procedure. When it receives a mouse-down event in an inactive window, for example, 
your application calls SelectWindow, which brings the selected window to the front, 
removes the highlighting from the previously active window, and adds highlighting to 
the selected window. The SelectWindow procedure then generates two activate events: 
the first one tells your application to deactivate the previously active window; the 
second, to activate the newly active window. 
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When you receive the event for the previously active window, you 
m hide the controls and size box 
m remove or alter any highlighting of selections in the window 


When you receive the event for the newly active window, you 
m draw the controls and size box 


m restore the content area as necessary, adding the insertion point in its former location 
or highlighting any previously highlighted selections 

If the newly activated window also needs updating, your application also receives an 

update event, as described in the previous section, “Handling Update Events.” 


Note 

A switch to one of your application’s windows from a different 

application is handled through suspend and resume events, not activate 

events. See the chapter “Event Manager” in this book for a description 

of how your application can share processing time. # 

Listing 4-11 illustrates the application-defined procedure DoActivate, which handles 
activate events. 


Listing 4-11 Handling activate events 


PROCEDURE DoActivate (window: WindowPtr; activate: Boolean; 
event: EventRecord); 





VAR 
windowType: Integer; 
myData: MyDocRecHnd; 
growRect: Rect; 
BEGIN 
{determine type of window as defined by this application} 
windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyFindModelessDialogBox: {modeless Find dialog box} 


DoActivateFindDBox (window, event); 
{modeless Check Spelling dialog box} 





kMyCheckSpellingModelessDialogBox: 





DoActivateCheckSpellDBox (window, event); 


kMyDocWindow: {document window} 
BEGIN 
myData := MyDocRecHnd(GetWRefCon(window)); {get document record} 


HLock (Handle (myData) ); {lock document record} 
WITH myData** DO 
IF activate THEN {window is becoming active} 
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BEGIN 

{restore selections and insert caret--if using } 

{ TextEdit, for example, call TEActivate} 

TEActivate (editRec) ; 

MyAdjustMenus; {adjust menus for window} 
{handle the controls} 

docVScroll**%.contrlVis kControlVisible; 

docHScroll**.contrlVis := kControlVisible; 

InvalRect (docVScroll**.contrlRect) ; 

InvalRect (docHScroll**.contrlRect) ; 


growRect := window*’%.portRect; 
WITH growRect DO {handle the size box} 
BEGIN {adjust for the scroll bars} 
top := bottom - kScrollbarAdjust; 
left := right - kScrollbarAdjust; 
END; 
InvalRect (growRect) ; 
END 
ELSE {window is becoming inactive} 
BEGIN 
TEDeactivate (editRec) ; {call TextEdit to deactivate data} 


HideControl (docVScroll); {hide the scroll bars} 
HideControl (docHScroll); 


DrawGrowlcon (window) ; {draw the size box} 
END; 
HUnLock (Handle (myData) ); {unlock document record} 


END; {of kMyDocWindow statement } 
END; {of CASE statement } 
END; 


The DoActivate procedure first determines the general type of the window; that is, 
it calls an application-defined function that returns a constant identifying the type 

of the window: a Find dialog box, a Check Spelling dialog box, or a document window. 
Listing 4-1 on page 4-25 shows the MyGetWindowType function 


If the target of the activate event is a dialog box window, DoActivate calls other 
application-defined routines for activating and deactivating those dialog boxes. The 
DoActivateFindDBox and DoActivateCheckSpel11DBox routines are not shown 
here. (The DoActivate procedure does not check for alert boxes and modal dialog 
boxes, because the Dialog Manager’s ModalDialog procedure automatically handles 
activate events.) 
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If the target is a document window and the activate event specifies that the window is 
becoming active, DoActivate highlights any user selections in the window and draws 
the insertion point where appropriate. It then makes the controls visible, adds the area 
occupied by the scroll bars to the update region, and adds the area occupied by the size 
box to the update region. (Placing window area in the update region guarantees an 
update event. When the application receives the update event, it calls the application- 
defined procedure DoUpdate to draw the update region, which in this case includes the 
size box and scroll bars.) 


If the target is a document window, and the activate event specifies that the window 

is becoming inactive, the DoActivate procedure calls the TextEdit procedure 
TEDeactivate to remove highlighting from user selections, calls the Control Manager 
procedure HideCont rol to hide the scroll bars, and calls the Window Manager 
procedure DrawGrowIcon to draw the size box and the outline of the scroll bar area. 





Moving a Window 


When the user drags a window by the title bar (except for the close and zoom box 
regions), the window should move, following the cursor as it moves on the 
desktop. Your application can easily let the user move the window by calling the 
DragWindow procedure. 


The DragWindow procedure draws an outline of the window on the screen and 
moves the outline as the user moves the mouse. When the user releases the mouse 
button, DragWindow calls the MoveWindow function, which redraws the window in 
its new location. 


For an example of moving a window, see the inDrag case in Listing 4-9 on page 4-44. 


Zooming a Window 


The zoom box allows the user to alternate quickly between two window positions and 
sizes: the user state and the standard state. 


The user state is the window size and location established by the user. If your 
application does not supply an initial user state, the user state is simply the size and 
location of the window when it was created, until the user resizes it. 


The standard state is the window size and location that your application considers most 
convenient, considering the function of the document and the screen space available. In 
a word-processing application, for example, a standard-state window might show a 

full page, if possible, or a page of full width and as much length as fits on the screen. 

If the user changes the page size through Page Setup, the application might adjust the 
standard state to reflect the new page size. If your application does not define a standard 
state, the Window Manager automatically sets the standard state to the entire gray 
region on the main screen, minus a three-pixel border on all sides. (See Macintosh Human 
Interface Guidelines for a detailed description of how your application determines where 
to open and zoom windows.) The user cannot change a window’s standard state. 


Using the Window Manager 4-53 


4-54 


CHAPTER 4 


Window Manager 


The user and standard states are stored in a record whose handle appears in the 
dataHandle field of the window record. 


TYPE WStateData = 





RECORD 
userState: Rect; {size and location established by user} 
stdState: Rect; {size and location established by } 
{ application} 
END; 


The Window Manager sets the initial values of the userState and stdState fields 
when it fills in the window record, and it updates the userState field whenever the 
user resizes the window. You typically compute the standard state every time the user 
zooms to the standard state, to ensure that you’re zooming to an appropriate location. 


When the user presses the mouse button with the cursor in the zoom box, the 

F indWindow function specifies whether the window is in the user state or the standard 
state: when the window is in the standard state, FindWindow returns inZoomIn 
(meaning that the window is to be zoomed “in” to the user state); when the window is in 
the user state, FindWindow returns inZoomOut (meaning that the window is to be 
zoomed “out” to the standard state). 


When FindWindow returns either inZoomIn or inZoomOut, your application can call 
the TrackBox function to handle the highlighting of the zoom box and to determine 
whether the cursor is inside or outside the box when the button is released. If TrackBox 
returns TRUE, your application can call the ZoomWindow procedure to resize the 
window (after computing a new standard state). If TrackBox returns FALSE, your 
application doesn’t need to do anything. Listing 4-9 on page 4-44 illustrates the use of 
TrackBox in an event-handling routine. 


Listing 4-12 illustrates an application-defined procedure, DoZoomWindow, which an 
application might call when TrackBox returns TRUE after FindWindow returns either 
inZoomIn or inZoomOut. Because the user might have moved the window toa 
different screen since it was last zoomed, the procedure first determines which screen 
contains the largest area of the window and then calculates the ideal window size for 
that screen before zooming the window. 


The screen calculations in the DoZoomWindow procedure depend on the routines for 
handling graphics devices that were introduced at the same time as Color QuickDraw. 
Therefore, DoZoomWindow checks for the presence of Color QuickDraw before 
comparing the window to be zoomed with the graphics devices in the device list. If 
Color QuickDraw is not available, DoZoomWindow assumes that it’s running on a 
computer with a single screen. 
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Listing 4-12 Zooming a window 


PROCEDURE DoZoomWindow (thisWindow: windowPtr; zoomInOrOut: Integer) ; 
VAR 


gdNthDevice, gdZoomOnThisDevice: GDHandle; 








savePort: GrafPtr; 

windRect, zoomRect, theSect: Rect; 

sectArea, greatestArea: LongInt; 

wlitleHeight: Integer; 

sectFlag: Boolean; 
BEGIN 


GetPort (savePort) ; 
SetPort (thisWindow) ; 


EraseRect (thisWindow’.portRect) ; {erase to avoid flicker} 
IF zoomInOrOut = inZoomOut THEN {zooming to standard state} 
BEGIN 
IF NOT gColorQDAvailable THEN {assume a single screen and } 
BEGIN { set standard state to full screen} 
zoomRect := screenBits.bounds; 


InsetRect (zoomRect, 4, 4); 


WStateDataHandle (WindowPeek (thisWindow) *.dataHandle) **.stdState 


:= zoomRect; 
END 
ELSE {locate window on available graphics devices} 
BEGIN 
windRect := thisWindow%’.portRect; 
LocalToGlobal (windRect.topLeft) ; {convert to global coordinates} 


LocalToGlobal (windRect .botRight) ; 


{calculate height of window's title bar} 





wlitleHeight := windRect.top - 1 - 
WindowPeek (thisWindow) *.strucRgn**.rgnBBox.top; 
windRect.top := windRect.top - wTitleHeight; 
gdNthDevice := GetDeviceList; 
greatestArea := 0; {initialize to 0} 


{check window against all gdRects in gDevice list and remember } 
{ which gdRect contains largest area of window} 
WHILE gdNthDevice <> NIL DO 
IF TestDeviceAttribute(gdNthDevice, screenDevice) THEN 
IF TestDeviceAttribute(gdNthDevice, screenActive) THEN 
BEGIN 
{The SectRect routine calculates the intersection } 
{ of the window rectangle and this gDevice } 
{ rectangle and returns TRUE if the rectangles intersect, } 
{ FALSE if they don't.} 
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sectFlag := SectRect (windRect, gdNthDevice**.gdRect, 
theSect) ; 

{determine which screen holds greatest window area} 

{first, calculate area of rectangle on current device} 

WITH theSect DO 


sectArea := LongInt (right - left) * (bottom - top); 
IF sectArea > greatestArea THEN 
BEGIN 
greatestArea := sectArea; {set greatest area so far} 
gdZoomOnThisDevice := gdNthDevice; {set zoom device} 
END; 
gdNthDevice := GetNextDevice (gdNthDevice) ; 





END; {of WHILE} 
{if gdZoomOnThisDevice is on main device, allow for menu bar height} 
IF gdZoomOnThisDevice = GetMainDevice THEN 


wlitleHeight := wTitleHeight + GetMBarHeight; 
WITH gdZoomOnThisDevice**.gdRect DO {create the zoom rectangle} 
BEGIN 


{set the zoom rectangle to the full screen, minus window title } 
{ height (and menu bar height if necessary), inset by 3 pixels} 
SetRect (zoomRect, left + 3, top + wTitleHeight + 3, 
right - 3, bottom - 3); 
{If your application has a different "most useful" standard } 
{ state, then size the zoom window accordingly. } 
{set up the WStateData record for this window} 
WStateDataHandle (WindowPeek (thisWindow) *.dataHandle) **.stdState 


:= zoomRect; 
END; 
END; 
END; {of inZoomOut } 
{if zoomInOrOut = inZoomIn, just let ZoomWindow zoom to user state} 
{zoom the window frame} 
ZoomWindow(thisWindow, zoomInOrOut, (thisWindow = FrontWindow) ); 
MyResizeWindow (thisWindow) ; {application-defined window-sizing routine} 


SetPort (savePort) ; 
END; (of DoZoomWindow) 


If the user is zooming the window to the standard state, DoZoomWindow calculates a 
new standard size and location based on the application’s own considerations, the 
current location of the window, and the available screens. The DoZoomWindow 
procedure always places the standard state on the screen where the window is currently 
displayed or, if the window spans screens, on the screen containing the largest area 

of the window. 
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The bulk of the code in Listing 4-12 is devoted to determining which screen should 
display the window in the standard state. The sample code shown here establishes 

a standard state that simply occupies the gray area on the chosen screen, minus 

three pixels on all sides. Your application should establish a standard state appropriate 
to its own documents. When calculating the standard state, move the window as little 
as possible from the user state. If possible, anchor one corner of the standard state 
rectangle to one corner of the user state rectangle. 


If the user is zooming the window to the user state, DoZoomWindow doesn’t have to 
perform any calculations, because the user state rectangle stored in the state data record 
should represent a valid screen location. 


After calculating the standard state, if necessary, DoZoomWindow calls the ZoomWindow 
procedure to redraw the window frame in the new size and location and then calls the 
application-defined procedure MyResizeWindow to redraw the window’s content 
region. Listing 4-14 on page 4-59 shows the MyResi zeWindow procedure. 


Resizing a Window 


The size box, in the lower-right corner of a window’s content region, allows the user to 
change a window’s size. 


When the user positions the cursor in the size box and presses the mouse button, your 
application can call the Window Manager’s GrowWindow function. This function 
displays a grow image—a gray outline of the window’s frame and scroll bar areas, 
which expands or contracts as the user drags the size box. The grow image indicates 
where the window edges would be if the user released the mouse button at any 

given moment. 


To avoid unmanageably large or small windows, you supply lower and upper size limits 
when you call GrowWindow. The sizeRect parameter to GrowWindow specifies both 
the lower and upper size limits in a single structure of type Rect. The values in the 
sizeRect structure represent window dimensions, not screen coordinates: 


m You supply the minimum vertical measurement in sizeRect .top. 

m You supply the minimum horizontal measurement in sizeRect.left. 
m You supply the maximum vertical measurement in sizeRect .bottom. 
m You supply the maximum horizontal measurement in sizeRect.right. 


Most applications specify a minimum size big enough to include all parts of the structure 
area and the scroll bars. Because the user cannot move the cursor beyond the edges of 
the screen, you can safely set the maximum size to the largest possible rectangle. 


When the user releases the mouse button, GrowWindow returns a long integer that 
describes the window’s new height (in the high-order word) and width (in the low-order 
word). A value of 0 means that the window’s size did not change. When GrowWindow 
returns any value other than 0, you call Si zeWindow to resize the window. 
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Note 
Use the utility functions HiWordand LoWord to retrieve the high-order 
and low-order words, respectively. @ 


When you change a window’s size, you must erase and redraw the window’s scroll bars. 


Listing 4-13 illustrates the application-defined procedure DoGrowWindow for tracking 
mouse activity in the size box and resizing the window. 


Listing 4-13 Resizing a window 


PROCEDURE DoGrowWindow (thisWindow: windowPtr; 
event: EventRecord); 


VAR 
growSize: LongInt; 
limitRect: Rect; 
oldViewRect: Rect; 
locUpdateRgn: RgnHandle; 
theResult: Boolean; 
myData: MyDocRecHnd; 
BEGIN 
{set up the limiting rectangle: kMinDocSize = 64 } 


{ kMaxDocSize 65535} 
SetRect (limitRect, kMinDocSize, kMinDocSize, kMaxDocSize, 
kMaxDocSize) ; 


{call Window Manager to let user drag size box} 


growSize := GrowWindow(thisWindow, event.where, limitRect); 
IF growSize <> 0 THEN {if user changed size, } 
BEGIN { then resize window} 

myData := MyDocRecHnd (GetWRefCon (thisWindow) ); 

oldViewRect := myData**.editRec**.viewRect; 

locUpdateRgn := NewRgn; 


{save update region in local coordinates} 

MyGetLocalUpdateRgn (thisWindow, locUpdateRgn) ; 

{resize the window} 

SizeWindow(thisWindow, LoWord(growSize), HiWord(growSize), 

TRUE) ; 

MyResizeWindow (thisWindow) ; 

{find intersection of old viewRect and new viewRect } 

theResult := SectRect (oldViewRect, 
myData**.editRec**.viewRect, 
oldViewRect) ; 

{validate the intersection (don't update) } 

ValidRect (oldViewRect) ; 
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{invalidate any prior update region} 
InvalRgn (locUpdateRgn) ; 
DisposeRgn (locUpdateRgn) ; 

END; 

END; 





When the user presses the mouse button while the cursor is in the size box, the 
procedure that handles mouse-down events (DoMouseDown, shown on page 4-44) calls 
the application-defined DoGrowWindow procedure. The DoGrowWindow procedure 
calls the Window Manager function GrowWindow, which tracks mouse movement as 
long as the button is held down. If the user drags the size box before releasing the mouse 
button, GrowWindow returns a nonzero value, and DoGrowWindow prepares to resize 

the window. First DoGrowWindow saves the current view rectangle in the variable 
oldViewRect. It will use this information later, when redrawing the content region of 
the window in its new size. The GrowWindow procedure also saves the current update 
region, in local coordinates, in the region LocUpdateRgn, so that it can restore the 
update region after doing its own update-region maintenance. (This step is necessary 
only if an application allows user input to accumulate into the update region, drawing in 
response to update events instead of drawing into the window immediately.) 


After saving the current view rectangle and the current update region, DoGrowWindow 
calls the Window Manager procedure $izeWindow to draw the window in its new 

size. The DoGrowWindow procedure then calls the application-defined procedure 
MyResizeWindow, which adjusts the window scroll bars and window contents to the 
new size. Listing 4-14 illustrates the application-defined MyResizeWindow procedure. 


After calling SizeWindow, DoGrowWindow calculates the intersection of the old view 
rectangle and the new view rectangle. It uses this area to revalidate unchanged portions 
of the window (that is, to remove them from the update region), because the 
MyResizeWindow procedure invalidates the entire window (that is, places the entire 
window in the update region). This way, only the changed parts of the content area are 
redrawn when the application receives its next update event. 


Listing 4-14 Adjusting scroll bars and content region when resizing a window 





PROCEDURE MyResizeWindow (window: WindowPtr); 
BEGIN 
WITH window’ DO 
BEGIN 
{adjust scroll bars and contents-- } 











{ see the chapter “Control Manager” for implementation} 
MyAdjustScrollbars (window, TRUE); 
MyAdjustTE (window) ; 
{invalidate content region, forcing an update} 
InvalRect (portRect) ; 
END; 
END; {MyResizeWindow} 
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Listing 4-15 illustrates the application-defined procedure MyGet LocalUpdateRgn, 
which supplies a window’s update region in local coordinates. The 

MyGet LocalUpdateRgn procedure uses the QuickDraw routines CopyRgn and 
OffsetRgn, documented in Inside Macintosh: Imaging. 


Listing 4-15 Converting a window region to local coordinates 


PROCEDURE MyGetLocalUpdateRgn (window: WindowPtr; 
localRgn: RgnHandle) ; 











{save old update region} 
CopyRgn (WindowPeek (window) *.updateRgn, localRgn) ; 
WITH window’.portBits.bounds DO 
OffsetRgn(localRgn, left, top); {convert to local coords} 
END; {MyGetLocalUpdateRgn } 


Closing a Window 


The user closes a window either by clicking the close box, in the upper-left corner of the 
window, or by choosing Close from the File menu. 


When the user presses the mouse button while the cursor is in the close box, your 
application calls the TrackGoAway function to track the mouse until the user releases 
the button, as illustrated in Listing 4-9 on page 4-44. If the user releases the button while 
the cursor is outside the close box, TrackGoAway returns FALSE, and your application 
does nothing. If TrackGoAway returns TRUE, your application invokes its own 
procedure for closing a window. 


The specific steps you take when closing a window depend on what kind of information 
the window contains and whether the contents need to be saved. The sample code in this 
chapter recognizes four kinds of windows: the modeless dialog box containing the Find 
dialog, the modeless dialog box containing the Spell Check dialog, a standard document 
window, and a window associated with a desk accessory that was launched in the 
application’s partition. 


Listing 4-16 illustrates an application-defined procedure, DoCloseCmd, that determines 
what kind of window is being closed and follows the appropriate strategy. The 
application calls DoCloseCmd when the user clicks a window’s close box or chooses 
Close from the File menu. 


Listing 4-16 Handling a close command 














PROCEDURE DoCloseCmd; 


VAR 
myWindow: WindowPtr; {pointer to window's record} 
myData: MyDocRecHnd; {handle to a document record} 
windowType: Integer; {application-defined window type} 
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BEGIN 
myWindow := FrontWindow; 
windowType := MyGetWindowType (myWindow) ; 
CASE windowType OF 
kMyFindModelessDialog: {for modeless dialog boxes, 
HideWindow (myWindow) ; { hide window} 
kMySpellModelessDialog: {for modeless dialog boxes, 
HideWindow (myWindow) ; { hide window} 
kDAWindow: {for desk accessories, close the DA} 
CloseDeskAcc (WindowPeek (myWindow) *.windowKind) ; 
kMyDocWindow: {for documents, handle file first} 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (myWindow) ) ; 
MyCloseDocument (myData) ; 
END; 
END; {of CASE} 
END; 


The DoCloseCmd procedure first determines which window is the active window 
and then calls the application-defined function MyGetWindowType to identify the 
window’s type, as defined by the application. If the window is a modeless dialog box, 
MyCloseCmd merely hides the window, leaving the data structures in memory. For 

a sample routine that displays a hidden window, see Listing 4-18 on page 4-64. 


If the window is associated with a desk accessory, the DoCloseCmd procedure calls 
the CloseDeskAcc procedure to close the desk accessory. This case is included 

only for compatibility; in System 7 desk accessories are seldom launched in an 
application’s partition. 

If the window is associated with a document, DoCloseCmd reads the document 
record and then calls the application-defined procedure MyCloseDocument to handle 
the closing of a document window. Listing 4-17 illustrates the MyCloseDocument 
procedure. 


Listing 4-17 Closing a document 


PROCEDURE MyCloseDocument (myData: MyDocRecHnd) ; 


VAR 
title: Str255; {window/document title} 
item: Integer; {item in Save Alert dialog box} 
docWindow: WindowPtr; {pointer to window record} 
event: EventRecord; {dummy record for DoActivate} 
myErr: OSErr; {variable for error-checking} 
BEGIN 
docWindow := FrontWindow; 


IF (myData**.windowDirty) THEN {changed since last save} 
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BEGIN 
GetWTitle(docWindow, title); {get window title} 
ParamText (title, '', "Ty ''); {set up dialog text} 


{deactivate window before displaying Save dialog} 
DoActivate (docWindow, FALSE, event); 
{put up Save dialog and retrieve user response} 








item := CautionAlert (kSaveAlertID, @MyEventFilter) ; 
IF item = kCancel THEN {user clicked Cancel} 
Exit (MyCloseDocument); {exit without closing} 
IF item = kSave THEN {user clicked Save} 
DoSaveCmd; {save the document } 
{otherwise user clicked Don't Save-- } 


{ close document in either case} 





myErr := DoCloseFile(myData); {close document} 
{Add your own error handling. } 
END; 
{close window whether or not user saved} 
CloseWindow (docWindow) ; {close window} 
DisposePtr (Ptr (docWindow) ); {dispose of window record} 
END; 


The MyCloseDocument procedure checks the windowDirty field in the document 
record (described in “Managing Multiple Windows” beginning on page 4-23). If the 
value of windowDirty is TRUE, MyCloseDocument displays a dialog box giving the 
user a chance to save the document before closing the window. The dialog box gives 
the user the choices of canceling the close, saving the document before closing 

the window, or closing the window without saving the document. If the user 

cancels, MyCloseDocument merely exits. If the user opts to save the document, 
MyCloseDocument calls the application-defined routine DoSaveCmd, which is 

not shown here. (For a description of how to save and close a file, see the chapter 
“Introduction to File Management” in Inside Macintosh: Files.) Whether or not the 

user saves the document before closing the window, MyCloseDocument closes the 
document and finally removes the window from the screen and diposes of the memory 
allocated to the window record. 





Hiding and Showing a Window 


Wherever the user clicks a window’s close box, you remove the window from the 
screen. Sometimes, however, you might find it’s more efficient to merely hide the 
window, instead of removing its data structures. 


If your application includes a Find modeless dialog box that searches for a string, for 
example, you might want to keep the structures in memory as long as the user is 
working. When the user closes the dialog box by clicking the close box, you simply hide 
the window by calling the HideWindow procedure. The next time the user chooses the 
Find command, your dialog box window is already available, in the same location and 
with the same text selected as when it was last used. 
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To reverse the HideWindow procedure, you must call both ShowWindow, which makes 
the window visible, and SelectWindow, which makes it the active window. Figure 4-22 
illustrates how the three procedures affect the window’s status on the screen. 


Figure 4-22 The cumulative effects of HideWindow, ShowWindow, and SelectWindow 
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The application-defined procedure for closing a window—DoCloseCmd, described 
on page 4-60—hides the Find and Spell Check dialog box windows when the 

user closes them. Listing 4-18 illustrates a sample application-defined procedure, 
DoShowModelessFindDialogBox, for redisplaying the Find dialog box when the 
user next chooses the Find command. 





Listing 4-18 Showing a hidden dialog box 


PROCEDURE DoShowModelessFindDialogBox; 
BEGIN 
IF gFindDialog = NIL THEN {no Find dialog box exists yet} 
BEGIN 

{create Find dialog box} 








gFindDialog := GetNewDialog(rFindModelessDialog, NIL, 
Pointer(-1)); 
IF gFindDialog = NIL THEN {creation failed} 
Exit (DoShowModelessFindDialogBox) ; {exit} 
{store value that identifies dbox in window refCon field} 
SetWRefCon(gFindDialog, LongInt (kMyFindModelessDialog) ) 


ShowWindow (gFindDialog) ; {make dialog box visible} 
END 
ELSE {dialog box already exists} 
BEGIN 
ShowWindow (gFindDialog) ; {make it visible} 
SelectWindow (gFindDialog) ; {select it} 
END; 





The DoShowModelessFindDialogBox procedure first checks whether the Find 

dialog box already exists. If it doesn’t, then DoShowModelessFindDialogBox creates 
a new dialog box through the Dialog Manager. It stores the constant that represents 

the Find dialog box in the refCon field of the new window record, makes the window 
visible, and draws the dialog box contents. If the Find dialog box already exists, 
DoShowModelessFindDialogBox makes the dialog box window visible and selects it. 
When the Window Manager then generates an activate event, the application calls its 
own procedure to draw the contents. 
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Data Structures 


This section describes the Window Manager data structures: the window record, the 
color window record, the state data record, the window color table record, the auxiliary 
window record, and the window list. 


A window record or color window record describes an individual window. It includes 
the record for the graphics port in which the window is displayed. 


The state data record stores two rectangles, known as the user state and the standard 
state, which define the size and location of the window as specified by the user and by 
your application. Your application switches between the two states when the user clicks 
the zoom box. 


A window color table defines the colors to be used for drawing the window’s frame and 
highlighting selected text. Ordinarily, you use the default window color table, which 
produces windows in the colors selected by the user through the Color control panel. If 
your application has some unusual need to control the frame colors, you can set up your 
own window color tables. 


The Window Manager uses auxiliary window records to associate a window with its 
window color table. 


The Window Manager uses the window list to track all of the windows on the desktop. 


The Color Window Record 


The Window Manager maintains a window record or color window record for each 
window on the desktop. 


The Window Manager supplies routines that let you access the window record as 
necessary. Your application seldom changes fields in the window record directly. 


The CWindowRecord data type defines the window record for a color window. The 
CWindowPeek data type is a pointer to a color window record. The first field in 

the window record is in fact the record that describes the window’s graphics port. The 
CWindowPtr data type is defined as a pointer to the window’s graphics port. 


When Color QuickDraw is not available, you can create monochrome windows using 
the parallel data types WindowRecord, WindowPeek, and WindowPt r, described in the 
next section, “The Window Record.” 


For compatibility, the WindowPtr and WindowPeek data types can point to either a 
color window record or a monochrome window record. You use the WindowPtr data 
type to specify a window in most Window Manager routines, and you can use it to 
specify a graphics port in QuickDraw routines that take the GrafPtr data type. Note 
that you can access only the fields of the window’s graphics port, not the rest of the 
window record, through the WindowPt r and CWindowPtr data types. You use the 
WindowPeek and CWindowPeek data types in low-level Window Manager routines 
and in your own routines that access window record fields beyond the graphics port. 
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The routines that manipulate color windows get color information from the window 
color tables and the auxiliary window record described in the sections “The Window 
Color Table Record” on page 4-71 and “The Auxiliary Window Record” on page 4-73. 





TYPE CWindowPtr = “CGrafPtr; 
CWindowPeek = *CWindowRecord; 

TYPE CWindowRecord = 

RECORD 

port: CGrafPort; {window's graphics port} 
windowKind: Integer; {class of the window} 
visible: Boolean; {visibility} 
hilited: Boolean; {highlighting} 
goAwayFlag: Boolean; {presence of close box} 
spareFlag: Boolean; {presence of zoom box} 
strucRgn: RgnHandle; {handle to structure region} 
contRgn: RgnHandle; {handle to content region} 
updateRgn: RgnHandle; {handle to update region} 
windowDefProc: Handle; {handle to window definition } 

{ function} 
dataHandle: Handle; {handle to window state } 

{ data record} 
titleHandle: StringHandle; {handle to window title} 
titleWidth: Integer; {title width in pixels} 
controllist: ControlHandle; {handle to control list} 
nextWindow: CWindowPeek; {pointer to next window } 

{ record in window list} 
windowPic: PicHandle; {handle to optional picture} 
refCon: LongInt; {storage available to your } 

{ application} 

END; 


Field descriptions 


port The graphics port record that describes the graphics port in which 


the window is drawn. 


The graphics port record, which is documented in Inside Macintosh: 
Imaging, defines the rectangle in which drawing can occur, the 
window’s visible region, the window’s clipping region, and a 
collection of current drawing characteristics such as fill pattern, pen 


location, and pen size. 
windowKind The class of window—that is, how the window was created. 


The Window Manager fills in this field when it creates the window 
record. It places a negative value in windowKind when the window 
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was created by a desk accessory. (The value is the reference ID of 
the desk accessory.) This field can also contain one of two constants: 


CONST 
dialogKind = 2; {dialog or alert window} 
userKind = 8; {window created by an } 


{ application} 


The value dialogKind identifies all dialog or alert box windows, 
whether created by the system software or, indirectly through the 
Dialog Manager, by your application. The Dialog Manager uses this 
field to help it track dialog and alert box windows. 


The value userKind represents a window created directly by your 
application. 


visible A Boolean value indicating whether or not the window is visible. If 
the window is visible, the Window Manager sets this field to TRUE; 
if not, FALSE. Visibility means only whether or not the window is to 
be displayed, not necessarily whether you can see it on the screen. 
(For example, a window that is completely covered by other 
windows can still be visible, even if the user cannot see it on the 
screen.) 





hilited A Boolean value indicating whether the window is highlighted— 
that is, drawn with stripes in the title bar. Only the active window is 
ordinarily highlighted. When the window is highlighted, the 
hilited field contains TRUE; when not, FALSE. 








goAwayFlag A Boolean value indicating whether the window has a close box. 
The Window Manager fills in this field when it creates the window 
according to the information in the 'WIND' resource or the 
parameters passed to the function that creates the window. 





If the value of goAwayFlag is TRUE, and if the window type 
supports a close box, the Window Manager draws a close box when 
the window is highlighted. 


spareFlag A Boolean value indicating whether the window type supports 
zooming. The Window Manager sets this field to TRUE if the 
window’s type is one that includes a zoom box (zoomDocP roc, 
zoomNoGrow, or even modalDBoxProc + zoomDocP roc). 





strucRgn A handle to the structure region, which is defined in global 
coordinates. The structure region is the entire screen area covered 
by the window—that is, both the window contents and the window 
frame. 


contRgn A handle to the content region, which is defined in global 
coordinates. The content region is the part of the window that 
contains the document, dialog, or other data; the window controls; 
and the size box. 


updateRgn A handle to the update region, which is defined in global 
coordinates. The update region is the portion of the window that 
must be redrawn. It is maintained jointly by the Window Manager 
and your application. The update region excludes parts of the 
window that are covered by other windows. 
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windowDefProc 


dataHandle 


titleHandle 
titleWidth 


controlList 


nextWindow 


windowPic 


refCon 


Note 


A handle to the definition function that controls the window. 
There’s no need for your application to access this field directly. 


In Macintosh models that use only 24-bit addressing, this field 
contains both a handle to the window’s definition function and the 
window’s variation code. If you need to know the variation code, 
regardless of the addressing mode, call the GetWVariant function. 


Usually a handle to a data area used by the window definition 
function. 


For zoomable windows, dat aHandle contains a handle to the 
WStateData record, which contains the user state and standard 
state rectangles. The WStateData record is described in “The 
Window State Data Record” beginning on page 4-70. 


A window definition function that needs only 4 bytes of data can 
use the dataHandle field directly, instead of storing a handle to 
the data. The window definition function that handles 
rounded-corner windows, for example, stores the diameters of 
curvature in the dataHand1e field. 


A handle to the string that defines the title of the window. 
The width, in pixels, of the window’s title. 


A handle to the window’s control list, which is used by the Control 
Manager. (See the chapter “Control Manager” in this book for a 
description of control lists.) 


A pointer to the next window in the window list, that is, the 
window behind this window on the desktop. In the window record 
for the last window on the desktop, the next Window field is set 
to NIL. 


A handle to a QuickDraw picture of the window’s contents. The 
Window Manager initially sets the windowPic field to NIL. If 
you're using the window to display a stable image, you can use the 
SetWindowPic procedure to place a handle to the picture in this 
field. When the window’s contents need updating, the Window 
Manager then redraws the contents itself instead of generating an 
update event. 


The window’s reference value field, which is simply storage 

space available to your application for any purpose. The sample 
code in this chapter uses the refCon field to associate a window 
with the data it displays by storing a window type constant in 

the refCon field of alert and dialog window records and a handle 
to a document record in the refCon field of a document 

window record. 


The close box, drag region, zoom box, and size box are not included in 
the window record because they don’t necessarily have the formal data 
structure for regions as defined in QuickDraw. The window definition 
function determines where these regions are. 
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The Window Record 


If Color QuickDraw is not available, you create windows with a parallel data structure, 
the window record. The only difference between a color window record and a window 


record is that a color window record points to a color graphics port, which allows full 
use of Macintosh computers with color capability, and a window record points to a 
monochrome graphics port 


The data types that describe window records, WindowRecord, WindowPtr, and 
WindowPeek, are parallel to the data types that describe color window records, and the 
fields in the monochrome window record are identical to the fields in the color window 

record. For a complete description, see “The Color Window Record” beginning on 
page 4-65. 


TYPE 


TYPE 


R 





WindowPtr = 
WindowPeek = 


WindowRecord = 


F:CORD 


port: 
windowKind: 
visible: 
hilited: 
goAwayFlag: 
spareFlag: 
strucRgn: 
contRgn: 
updateRgn: 
windowDefProc: 


dataHandle: 


titleHandle: 
titleWidth: 
controlblist: 


nextWindow: 


windowPic: 


refCon: 


END; 
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“GrafPtr; 
“WindowRecord; 


GrafPort; 
Integer; 
Boolean; 





Boolean; 
Boolean; 
Boolean; 
RgnHandle; 
RgnHandle; 
RgnHandle; 
Handle; 


Handle; 


StringHandle; 
Integer; 
ControlHandle; 
WindowPeek; 


PicHandle; 
LongInt; 


{all fields have same use } 


{ as in color window record} 


{window's graphics port} 


{class of the window} 


{visibility} 
{highlighting} 
{presence of close box} 


{presence of zoom box} 


{handle 
{handle 
{handle to 
{handle to 
{ function} 
{handle to 


to 
to 


structure region} 


content region} 


update region} 


window definition } 


window state } 


{ data record} 


{handle to 


window title} 


{title width in pixels} 


{handle to 


control list} 


{pointer to next window } 


{ record in window list} 


{handle to optional picture} 


{storage available to your } 


{ application} 
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The Window State Data Record 


4-70 


The zoom box allows the user to alternate quickly between two window positions and 
sizes: the user state and the standard state. The Window Manager stores the user state 
and your application stores the standard state in the window state data record, whose 
handle appears in the dataHand1e field of the window record. 


The WStateData record data type defines the window state data record. 


TYPE WStateDataPtr = *“WStateData; 
WStateDataHandle = “WStateDataPtr; 








WStateData = 
RECORD 
userState: Rect; {size and location established by user} 
stdState: Rect; {size and location established by app} 
END; 


Field descriptions 
userState 


stdState 


A rectangle that describes the window size and location established 
by the user. 


The Window Manager initializes the user state to the size and 
location of the window when it is first displayed, and then updates 
the userState field whenever the user resizes a window. 
Although the user state specifies both the size and location of the 
window, the Window Manager updates the state data record only 
when the user resizes a window—not when the user merely moves 
a window. 


The rectangle describing the window size and location that your 
application considers the most convenient, considering the function 
of the document, the screen space available, and the position of the 
window in its user state. If your application does not define a 
standard state, the Window Manager automatically sets the 
standard state to the entire gray region on the main screen, minus a 
three-pixel border on all sides. The user cannot change a window’s 
standard state. 


Your application typically calculates and sets the standard state 
each time the user zooms to the standard state. In a word- 
processing application, for example, a standard state window might 
show a full page, if possible, or a page of full width and as much 
length as fits on the screen. If the user changes the page size 
through Page Setup, the application might adjust the standard state 
to reflect the new page size. (See Macintosh Human Interface 
Guidelines for a detailed description of how your application 
determines where to open and zoom windows.) 


The ZoomWindow procedure changes the size of a window according to the values in the 
window state data record. The procedure changes the window to the user state when the 
user zooms “in” and to the standard state when the user zooms “out.” For a detailed 
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description of zooming windows, see “Zooming a Window” beginning on page 4-53. For 
descriptions of the routines you call when zooming windows, see “Zooming Windows” 
beginning on page 4-101. 


The Window Color Table Record 


The user controls the colors used for the window frame and text highlighting through 
the Color control panel. Ordinarily, your application doesn’t override the user’s color 
choices, which are stored in a default window color table. If you have some extraordi- 
nary need to control window colors, you can do so by defining window color tables for 
your application’s windows. 


The Window Manager maintains window color information tables in a data structure of 
type WinCTab. 


You can define your own window color table and apply it to an existing window 
through the SetWinColor procedure. 


To establish the window color table for a window when you create it, you provide 
a window color table ('wctb') resource with the same resource ID as the 'WIND' 
resource that defines the window. 


The WCTabPtr data type is a pointer to a window color table record, and the 
WTabHand1e is a handle to a window color table record. 


TYPE WCTabPtr = “WinCTab; 
WCTabHandle = “WCTabPtr; 


The WinCTab data type defines a window color table record. 


TYPE WinCTab = 


RECORD 
wCSeed: LongInt; {reserved} 
wCReserved: Integer; {reserved} 
ctSize: Integer; {number of entries in table -1} 
ctTable: ARRAY[0..4] OF ColorSpec; 
{array of color specification } 
{ records} 
END; 


Field descriptions 


wCSeed Reserved. 
wCReserved Reserved. 
ctSize The number of entries in the table, minus 1. If you’re building a 


color table for use with the standard window definition function, 
the maximum value of this field is 12. Custom window definition 
functions can use color tables of any size. 
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ctTable 


An array of colorSpec records. 


In a window color table, each colorSpec record specifies a 
window part in the first word and an RGB value in the other 
three words: 


TYPE ColorSpec = 


RECORD 
value: Integer; {part identifier} 
rgb: RGBColor; {RGB value} 

END; 





The value field of a colorSpec record specifies a constant that 
defines which part of the window the color controls. For the 
window color table used by the standard window definition 
function, you can specify these values with these meanings: 


CONST 

wContentColor = 0; {content region background} 

wFrameColor => {window outline} 

wTextColor = 2; {window title and button } 
{ text} 

wHiliteColor = 3; {reserved} 

wTlitleBarColor = 4; {reserved} 


wHiliteColorLight = 5; {lightest stripes in } 
{ title bar and lightest } 
{ dimmed text} 


wHiliteColorDark = 6; {darkest stripes in } 
{ title bar and } 
{ darkest dimmed } 
{ text} 
wlitleBarLight = 7; {lightest parts of } 


{ title bar background} 
wlitleBarDark = 8; {darkest parts of } 
{ title bar background} 


wDialogLight = 9; {lightest element } 

{ of dialog box frame} 
wDialogDark = 10; {darkest element of } 

{ dialog box frame} 
wlingeLight = 11; {lightest window tinging} 
wlingeDark = 12; {darkest window tinging} 
Note 


The part codes in System 5 and System 6 are significantly different 
from the part codes described here, which apply only to System 7. @ 
The window parts can appear in any order in the table. 

The rgb field of a ColorSpec record contains three words of data 
that specify the red, green, and blue values of the color to be used. 
The RGBColor data type is defined in Inside Macintosh: Imaging. 
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When your application creates a window, the Window Manager first looks for a resource 
of type 'wctb' with the same resource ID as the 'WIND' resource used for the window. 
If it finds one, it creates a window color table for the window from the information in 
that resource, and then displays the window in those colors. If it doesn’t find a window 
color table resource with the same resource ID as your window resource, the Window 
Manager uses the default system window color table, read into the heap during 
application startup. 


After creating a window, you can change the entries in a window’s window color table 
with the SetWinColor procedure, described on page 4-114. 


See “The Window Color Table Resource” on page 4-127 for a description of the window 
color table resource. 


The Auxiliary Window Record 


The auxiliary window record specifies the color table used by a window and contains 
reference information used by the Dialog Manager and the Window Manager. 


The Window Manager creates and maintains the information in an auxiliary window 
record; your application seldom, if ever, needs to access an auxiliary window record. 


TYPE AuxWinPtr = “AuxWinRec; 
AuxWinHandle = *AuxWinPtr; 
AuxWinRec = 
RECORD 
awNext: AuxWinHandle; {handle to next record} 
awOwner: WindowPtr; {pointer to window } 
{ associated with this } 
{ record} 
awCTable: CTabHandle; {handle to color table} 
dialogCItem: Handle; {storage used by } 
{ Dialog Manager} 
awFlags: LongInt; {reserved} 
awReserved: CTabHandle; {reserved} 
awRefCon: LongInt; {reference constant, } 
{ for application's use} 
END; 


Field descriptions 

awNext A handle to the next record in the auxiliary window list, used by 
the Window Manager to maintain the auxiliary window list as a 
linked list. If a window is using the default auxiliary window 
record, this value is NIL. 

awOwner A pointer to the window that uses this record. The awOwner field of 
the default auxiliary window record is set to NIL. 
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awCTable A handle to the window’s color table. Unless you specify otherwise, 
this is a handle to the system window color table. 

dialogCItem Private storage for use by the Dialog Manager. 

awFlags Reserved. 

awReserved Reserved. 

awRefCon The reference constant, typically used by an application to associate 


the auxiliary window record with a document record. 


Except in unusual circumstances, your application doesn’t need to manipulate window 
color tables or the auxiliary window record. 


For compatibility with other applications in the shared environment, your application 
should not manipulate system color tables directly but should go through the Palette 
Manager, documented in Inside Macintosh: Imaging. If your application provides its own 
window and control definition functions, these functions should apply the user’s 
desktop color choices the same way the standard window and control definition 
functions do. 


The Window List 


The Window Manager maintains information about the windows on the desktop in a 
private structure called the window list. The window list contains pointers to all windows 
on the desktop, both visible and invisible, and contains other information that the 
Window Manager uses to maintain the desktop. 


Your application should not directly access the information in a window list. The 
structure of the window list is private to the Window Manager. 


The global variable WindowList contains a pointer to the first window in the 
window list. 


Window Manager Routines 


This section describes the complete set of routines for creating, displaying, and 
managing windows. 


Initializing the Window Manager 
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Before using any other other Window Manager routines, you must initialize the Window 
Manager by calling the InitWindows procedure. 


As part of initialization, InitWindows creates the Window Manager port, a graphics 
port that occupies all of the main screen. The Window Manager port is named 
WMgrCPort on Macintosh computers equipped with Color QuickDraw and WMgrPort 
on computers with only QuickDraw. 
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Ordinarily, your application does not need to know about the Window Manager port. 
If necessary, however, you can retrieve a pointer to it by calling the procedure 
GetWMgrPort or Get CWMgrPort. Your application should not draw directly into 
the Window Manager port, except through custom window definition functions. 


The Window Manager draws your application’s windows into the Window Manager 
port. The port rectangle of the Window Manager port is the bounding rectangle of the 
main screen (screenBits. bounds). To accommodate systems with multiple monitors, 
QuickDraw recognizes a port rectangle of screenBits.bounds as a special case and 
allows drawing on all parts of the desktop. 


InitWindows 


The procedure InitWindows initializes the Window Manager for your application. 
Before calling InitWindows, you must initialize QuickDraw and the Font Manager by 
calling the InitGraf and InitFonts procedures, documented in Inside Macintosh: 
Imaging and Inside Macintosh: Text. 


PROCEDURE InitWindows; 


DESCRIPTION 
The InitWindows procedure initializes the Window Manager. 


ASSEMBLY-LANGUAGE INFORMATION 
When the desktop needs to be redrawn any time after initialization, the Window 
Manager checks the global variable DeskHook, which can be used as a pointer to an 
application-defined routine for drawing the desktop. This variable is ordinarily set to 0, 
but not until after system startup. If you’re displaying windows in code that is to be 
executed during startup, set DeskHook to 0. Note that the use of the Window Manager’s 
global variables is not guaranteed to be compatible in system software versions later 
than System 6. 


Creating Windows 
You can create windows in two ways: 


m from a window resource (a resource of type 'WIND'), with the GetNewCWindow and 
GetNewWindow functions 


m from a collection of window characteristics passed as parameters to the NewCWindow 
and NewWindow functions 


Creating windows from resources allows you to localize your application for different 
languages and to change the characteristics of your windows during application 
development by changing only the window resources. 
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All four functions, GetNewCWindow, GetNewWindow, NewCWindow, and NewWindow, 
can allocate space in your application’s heap for the new window’s window record. For 
more control over memory use, you can allocate the space yourself and pass a pointer 
when creating a window. In either case, the Window Manager fills in the data structure 
and returns a pointer to it. 


GetNewCWindow 


DESCRIPTION 
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Use the Get NewCWindow function to create a color window with the properties defined 
in the 'WIND' resource with a specified resource ID. 


FUNCTION GetNewCWindow (windowID: Integer; wStorage: Ptr; 
behind: WindowPtr): WindowPtr; 


windowID The resource ID of the 'WIND' resource that defines the properties of 
the window. 


wStorage A pointer to memory space for the window record. 


If you specify a value of NIL for wStorage, the GetNewCWindow 
function allocates the window record as a nonrelocatable object in the 
heap. You can reduce the chances of heap fragmentation by allocating the 
memory your application needs for window records early in your 
initialization code. Whenever you need to create a window, you can 
allocate memory from your own block and pass a pointer to it in the 
wStorage parameter. 


behind A pointer to the window that appears immediately in front of the new 
window on the desktop. 


To place a new window in front of all other windows on the desktop, 
specify a value of Pointer (-1). When you place a window in front of 
all others, Get NewCWindow removes the highlighting from the 
previously active window, highlights the newly created window, and 
generates the appropriate activate events. Note that if you create an 
invisible window in front of all others on the desktop, the user sees no 
active window until you make the new window visible (or make another 
window active). 


To place a new window behind all other windows, specify a value of NIL. 


The Get NewCWindow function creates a new color window from the specified window 
resource and returns a pointer to the newly created window record. You can use the 
returned window pointer to refer to this window in most Window Manager routines. If 
GetNewCWindow is unable to read the window or window definition function from the 
resource file, it returns NIL. 
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The GetNewCWindow function looks for a 'wctb' resource with the same resource ID 
as that of the 'WIND' resource. If it finds one, it uses the window color information in 
the 'wctb' resource for coloring the window frame and highlighting selected text. 


If the window’s definition function (specified in the window resource) is not already in 
memory, Get NewCWindow reads it into memory and stores a handle to it in the window 
record. It allocates space in the application heap for the structure and content regions of 
the window and asks the window definition function to calculate those regions. 


To create the window, GetNewCWindow retrieves the window characteristics from the 
window resource and then calls the NewCWindow function, passing the characteristics 
as parameters. 


The Get NewCWindow function creates a window in a color graphics port. Before calling 
GetNewCWindow, verify that Color QuickDraw is available. Your application typically 
sets up its own global variables reflecting the system setup during initialization by 
calling the Gestalt function.SeeInside Macintosh: Overview formoreinformationabout 
establishing the local configuration. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


Note that the Get NewCWindow function returns a value of type WindowPt r, not 
CWindowPtr. 


If you let the Window Manager create the window record in your application’s heap, call 
DisposeWindow to dispose of the window’s window record. If you allocated the 
memory for the window record yourself and passed a pointer to the storage to 

Get NewCWindow, use the procedure CloseWindow to close the window and the 
procedure DisposePtr, documented in Inside Macintosh: Memory, to dispose of the 
window record. 


See Listing 4-3 on page 4-28 for an example that calls GetNewCWindow to create a new 
window from a window resource. 


For more information about window characteristics and the window resource, see the 
description of NewCWindow beginning on page 4-79 and the description of the 'WIND' 
resource in the section “The Window Resource” beginning on page 4-124. 


For the procedures for closing a window and removing the structures from memory, see 
the descriptions of the DisposeWindow procedure on page 4-105, the CloseWindow 
procedure on page 4-104, and the DisposePtr procedure in Inside Macintosh: Memory. 
See Listing 4-17 on page 4-61 for an example of closing a document window. 
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GetNewWindow 


DESCRIPTION 
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Use the Get NewWindow function to create a new window from a window resource 
when Color QuickDraw is not available. The Get NewWindow function takes the same 
parameters as Get NewCWindow and returns a value of type WindowPtr. The only 
difference is that it creates a monochrome graphics port, not a color graphics port. 

The window record and graphics port record that describe monochrome and color 
graphics ports are the same size and can be used interchangeably in most Window 
Manager routines. 


FUNCTION GetNewWindow (windowID: Integer; wStorage: Ptr; 
behind: WindowPtr): WindowPtr; 


windowID The resource ID of the 'WIND' resource that defines the properties of the 
window. 


wStorage A pointer to memory space for the window record. 


If you specify a value of NIL for wStorage, the Get NewWindow function 
allocates the window record as a nonrelocatable object in the heap. You 
can reduce the chances of heap fragmentation by allocating the memory 
your application needs for window records early in your initialization 
code. Whenever you need to create a window, you can allocate memory 
from your own block and pass a pointer to it in the wSt orage parameter. 
behind A pointer to the window that appears immediately in front of the new 
window on the desktop. 
To place a new window in front of all other windows on the desktop, 
specify a value of Pointer (-1). When you place a window in front of 
all others, GetNewWindow removes the highlighting from the previously 
active window, highlights the newly created window, and generates the 
appropriate activate events. Note that if you create an invisible window 
in front of all others on the desktop, the user sees no active window until 
you make the new window visible (or make another window active). 


To place a new window behind all other windows, specify a value of NIL. 


Like GetNewCWindow, Get NewWindow creates anew window from a window resource, 
but it creates a monochrome window. The Get NewWindow function creates a new 
window from the specified window resource and returns a pointer to the newly created 
window record. You can use the returned window pointer to refer to this window in 
most Window Manager routines. If Get NewWindow is unable to read the window or 
window definition function from the resource file, it returns NIL. 


If the window’s definition function (specified in the window resource) is not already in 

memory, Get NewWindow reads it into memory and stores a handle to it in the window 

record. It allocates space in the application heap for the structure and content regions of 
the window and asks the window definition function to calculate those regions. 
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To create the window, GetNewWindow retrieves the window characteristics from the 
window resource and then calls the function NewWindow, passing the characteristics 
as parameters. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


If you let the Window Manager create the window record in your application’s heap, call 
DisposeWindow to dispose of the window’s window record. If you allocated the 
memory for the window record yourself and passed a pointer to Get NewWindow, use 

the procedure CloseWindow to close the window and the procedure DisposePtr, 
documented in Inside Macintosh: Memory, to dispose of the window record. 


For more information about window characteristics and the window resource, see the 
description of NewWindow beginning on page 4-82 and the description of the 'WIND' 
resource in the section “The Window Resource” beginning on page 4-124. 


For the procedures for closing a window and removing the structures from memory, see 
the descriptions of the DisposeWindow procedure on page 4-105, the CloseWindow 
procedure on page 4-104, and the DisposePtr procedure in Inside Macintosh: Memory. 


NewCWindow 


You can use the NewCWindow function to create a window with a specified list of 
characteristics. 


FUNCTION NewCWindow (wStorage: Ptr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
procID: Integer; behind: WindowPtr; 








goAwayFlag: Boolean; 
refCon: LongInt): WindowPtr; 


wStorage A pointer to the window record. If you specify NIL as the value of 
wStorage, NewCWindow allocates the window record as a nonrelocatable 
object in the application heap. You can reduce the chances of heap 
fragmentation by allocating memory from a block of memory reserved for 
this purpose by your application and passing a pointer to it in the 
wStorage parameter. 


boundsRect A rectangle, in global coordinates, specifying the window’s initial size 
and location. This parameter becomes the port rectangle of the window’s 
graphics port. For the standard window types, the boundsRect field 
defines the content region of the window. The NewCWindow function 
places the origin of the local coordinate system at the upper-left corner of 
the port rectangle. 
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Note 


The NewCWindow function actually calls the QuickDraw procedure 
OpenCPort to create the graphics port. The bitmap, pen pattern, 

and other characteristics of the window’s graphics port are the same 

as the default values set by OpenCPort, except for the character font, 
which is set to the application font instead of the system font. 


title A string that specifies the window’s title. 


If the title is too long to fit in the title bar, the title is truncated. If the 
window has a close box, characters are truncated at the end of the title; if 
there’s no close box, the title is centered and truncated at both ends. 


To suppress the title in a window with a title bar, pass an empty string, 
not NIL, in the title parameter. 





visible A Boolean value indicating visibility status: TRUE means that the Window 
Manager displays the window; FALSE means it does not. 





If the value of the visible parameter is TRUE, the Window Manager 
draws a new window as soon as the window exists. The Window 
Manager first calls the window definition function to draw the window 
frame. If the value of the goAwayFlag parameter is also TRUE and the 
window is frontmost (that is, if the value of the behind parameter is 
Pointer (-1) ), the Window Manager instructs the window definition 
function to draw a close box in the window frame. After drawing the 
frame, the Window Manager generates an update event to trigger your 
application’s drawing of the content region. 





When you create a window, you typically specify FALSE as the value of 
the visible parameter. When you're ready to display the window, you 
call the ShowWindow procedure, described on page 4-88. 


procID The window’s definition ID, which specifies both the window definition 
function and the variation code within that definition function. 


The Window Manager supports nine standard window types, which 
are handled by two window definition functions. You can create windows 
of the standard types by specifying one of the window definition ID 





constants: 
CONST 
documentProc = 0; {standard document } 

{ window, no zoom box} 
dBoxProc = 1; {alert box or modal } 

{ dialog box} 
plainDBox = 2; {plain box} 
altDBoxProc = 3; {plain box with shadow} 
noGrowDocProc = 4; {movable window, } 

{ no size box or zoom box} 
movableDBoxProc = 53 {movable modal dialog box} 
zoomDocProc = 8; {standard document window} 
zoomNoGrow = 12; {zoomable, nonresizable } 

{ window} 
rDocProc = 16; {rounded-corner window} 
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For a description of the nine standard window types, see “Types of 
Windows” beginning on page 4-8. 

You can control the diameter of curvature of rounded-corner windows by 
adding an integer to the rDocProc constant, as described in “The 
Window Resource” beginning on page 4-124. 


behind A pointer to the window that appears immediately in front of the new 
window on the desktop. 


To place a new window in front of all other windows on the desktop, 
specify a value of Pointer (—1). When you place a new window in front 
of all others, NewCWindow removes highlighting from the previously 
active window, highlights the newly created window, and generates 
activate events that trigger your application’s updating of both windows. 
Note that if you create an invisible window in front of all others on the 
desktop, the user sees no active window until you make the new window 
visible (or make another window active). 


To place a new window behind all other windows, specify a value of NIL. 


goAwayFlag A Boolean value that determines whether the window has a close box. If 
the value of goAwayFlag is TRUE and the window type supports a close 
box, the Window Manager draws a close box in the title bar and 
recognizes mouse clicks in the close region; if the value of goAwayF lag is 
FALSE or the window type does not support a close box, it does not. 

refCon The window’s reference constant, set and used only by your application. 
(See “Managing Multiple Windows” beginning on page 4-23 for some 
suggested ways to use the refCon parameter.) 


The NewCWindow function creates a window as specified by its parameters, adds it to 
the window list, and returns a pointer to the newly created window record. You can use 
the returned window pointer to refer to this window in most Window Manager routines. 
If NewCWindow is unable to read the window definition function from the resource file, it 
returns NIL. 


The NewCWindow function looks for a 'wctb' resource with the same resource ID as the 
"'WIND' resource. If it finds one, it uses the window color information in the 'wctb' 
resource for coloring the window frame and highlighting. 


If the window’s definition function is not already in memory, NewCWindow reads it 
into memory and stores a handle to it in the window record. It allocates space for the 
structure and content regions of the window and asks the window definition function 
to calculate those regions. 


Storing the characteristics of your windows as resources, especially window titles and 
window items, makes your application easier to localize. 


The NewCWindow function creates a window in a color graphics port. Creating color 
windows whenever possible ensures that your windows appear on color monitors with 
whatever color options the user has selected. Before calling GetNewCWindow, verify that 
Color QuickDraw is available. Your application typically sets up its own set of global 
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variables reflecting the system setup during initialization by calling the Gestalt 
function. See the chapter Inside Macintosh: Overview for more information about 
establishing the local configuration. 


Note that the function NewCWindow returns a value of type WindowPtr, not 
CWindowPtr. 


SPECIAL CONSIDERATIONS 


If you let the Window Manager create the window record in your application’s heap, 
call the DisposeWindow procedure to close the window and dispose of its window 
record. If you allocated the memory for the window record yourself and passed a 
pointer to NewCWindow, use the CloseWindow procedure to close the window and 

the DisposePtr procedure, documented in Inside Macintosh: Memory, to dispose of the 
window record. 


SEE ALSO 
For the procedures for closing a window and removing the structures from memory, see 
the descriptions of the DisposeWindow procedure on page 4-105, the CloseWindow 
procedure on page 4-104, and the DisposePtr procedure in Inside Macintosh: Memory. 
NewWindow 


Use the NewWindow function to create a new window with the characteristics specified 
by a list of parameters when Color QuickDraw is not available. The NewWindow 
function takes the same parameters as NewCWindow and, like NewCWindow, returns a 
WindowPtr as its function result. The only difference is that NewWindow creates a 
window ina monochrome graphics port, not a color graphics port. The window record 
and graphics port record that describe monochrome and color graphics ports are the 
same size and can be used interchangeably in most Window Manager routines. 


FUNCTION NewWindow (wStorage: Ptr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
theProc: Integer; behind: WindowPtr; 
goAwayFlag: Boolean; 
refCon: LongInt): WindowPtr; 


wStorage A pointer to the window record. If you specify NIL as the value of 
wStorage, NewWindow allocates the window record as a nonrelocatable 
object in the heap. You can reduce the chances of heap fragmentation by 
allocating the storage from a block of memory reserved for this purpose 
by your application and passing a pointer to it in the wStorage 
parameter. 
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boundsRect 


title 


visible 


theProc 


A rectangle, in global coordinates, specifying the window’s initial size 
and location. This parameter becomes the port rectangle of the window’s 
graphics port. For the standard window types, boundsRect defines 
the content region of the window. The NewWindow function places 

the origin of the local coordinate system at the upper-left corner of the 
port rectangle. 


Note 

The NewWindow function actually calls the QuickDraw procedure 
OpenPort to create the graphics port. The bitmap, pen pattern, and 
other characteristics of the window’s graphics port are the same as 
the default values set by OpenPort, except for the character font, 
which is set to the application font instead of the system font. The 
coordinates of the graphics port’s port boundaries and visible region 
are changed along with its port rectangle. @ 


A string that specifies the window’s title. 


If the title is too long to fit in the title bar, the title is truncated. If the 
window has a close box, characters at the end of the title are truncated; if 
there’s no close box, the title is centered and truncated at both ends. 


To suppress the title in a window with a title bar, pass an empty string, 
not NIL. 


A Boolean value indicating visibility status: TRUE means that the Window 
Manager displays the window; FALSE means it does not. 


If the value of the visible parameter is TRUE, the Window Manager 
draws a new window as soon as the window exists. The Window 
Manager first calls the window definition function to draw the window 
frame. If the value of the goAwayFlag parameter (described below) is 
also TRUE and the window is frontmost (that is, if the value of the 
behind parameter is Pointer (-1) ), the Window Manager instructs the 
window definition function to draw a close box in the window frame. 
After drawing the frame, the Window Manager generates an update 
event to trigger your application’s drawing of the content region. 





When you create a window, you typically specify FALSE as the value of 
the visible parameter. When you're ready to display the window, you 
call the ShowWindow procedure, described on page 4-88. 


The window’s definition ID, which specifies both the window definition 
function and the variation code for that definition function. 


The Window Manager supports nine standard window types, which are 
handled by two window definition functions. You can create windows of 
the standard types by specifying one of the type constants: 


CONST 
documentProc = 0; {standard document } 
{ window, no zoom box} 
dBoxProc = 1; {alert box or modal } 
{ dialog box} 
plainDBox = 2; {plain box} 
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altDBoxProc = 3; {plain box with shadow} 
noGrowDocProc = 4; {movable window, } 


{ no size box or zoom box} 


movableDBoxProc = 5; {movable modal dialog box} 
zoomDocProc = 8; {standard document window} 
zoomNoGrow = 12; {zoomable, nonresizable } 


{ window} 


rDocProc 16; {rounded-corner window} 
You can control the diameter of curvature of rounded-corner windows by 
adding an integer to the rDocProc constant, as described in “The 
Window Resource” beginning on page 4-124. 


behind A pointer to the window that appears immediately in front of the new 
window on the desktop. 


To place a new window in front of all other windows on the desktop, 
specify a value of Pointer (-1).When you place a new window in front 
of all others, NewWindow removes highlighting from the previously active 
window, highlights the newly created window, and generates activate 
events that trigger your application’s updating of both windows. Note 
that if you create an invisible window in front of all others on the 
desktop, the user sees no active window until you make the new window 
visible (or make another window active). 


To place a new window behind all other windows, specify a value of NIL. 


goAwayFlag A Boolean value that determines whether or not the window has a close 
box. If the value of goaAwayF lag is TRUE and the window type supports 
a close box, the Window Manager draws a close box in the title bar and 
recognizes mouse clicks in the close region; if the value of goAwayF lag is 
FALSE or the window type does not support a close box, it does not. 


refCon The window’s reference constant, set and used only by your application. 
(See “Managing Multiple Windows” beginning on page 4-23 for some 
suggested ways to use the refCon parameter.) 


The NewWindow function creates a window as specified by its parameters, adds it to the 
window list, and returns a pointer to the newly created window record. You can use the 
returned window pointer to refer to this window in most Window Manager routines. If 
NewWindow is unable to read the window definition function from the resource file, it 
returns NIL. 


If the window’s definition function is not already in memory, NewWindow reads it into 
memory and stores a handle to it in the window record. It allocates space for the 
structure and content regions of the window and asks the window definition function to 
calculate those regions. 


Storing the characteristics of your windows as resources, especially window titles and 
window items, makes your application easier to localize. 


Window Manager Reference 


CHAPTER 4 


Window Manager 


SPECIAL CONSIDERATIONS 


SEE ALSO 


If you let the Window Manager create the window record in your application’s heap, call 
the DisposeWindow procedure to close the window and dispose of its window record. 

If you allocated the memory for the window record yourself and passed a pointer to 
NewCWindow, use the CloseWindow procedure to close the window and the 
DisposePtr procedure, documented in Inside Macintosh: Memory, to dispose of the 
window record. 


For the procedures for closing a window and removing the structures from memory, see 
the descriptions of the DisposeWindow procedure on page 4-105, the CloseWindow 
procedure on page 4-104, and the DisposePtr procedure in Inside Macintosh: Memory. 


Naming Windows 


SetWTitle 


DESCRIPTION 


This section describes the procedures that set and retrieve a window’s title. 


Use the Set WTitle procedure to change a window's title. 


PROCEDURE SetWTitle (theWindow: WindowPtr; title: Str255); 





theWindow A pointer to the window’s window record. 


title The new window title. 


The SetWTitle procedure changes a window’s title to the specified string, both in the 
window record and on the screen, and redraws the window’s frame as necessary. 


When the user opens a previously saved document, you typically create a new (invisible) 
window with the title “untitled” and then call SetWTitle to give the window the 
document’s name before displaying it. You also call SetWTitle when the user saves a 
document under a new name. 


To suppress the title in a window with a title bar, pass an empty string, not NIL. 


Always use SetWTitle instead of directly changing the title in a window’s 
window record. 
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Use the Get WTitle procedure to retrieve a window’s title. 
PROCEDURE GetWTitle (theWindow: WindowPtr; VAR title: Str255); 


theWindow A pointer to the window record. 


title The window title. 


The Get WTitle procedure returns the title of the window in the title parameter. 


Your application seldom needs to determine a window’s title. It might need to do so, 
however, when presenting user dialog boxes during operations that can affect multiple 
files. A spell-checking command, for example, might display a dialog box that lets the 
user select from all currently open documents. 


When you need to retrieve a window’s title, you should always use Get WT it le instead 
of reading the title from a window’s window record. 


Displaying Windows 


This section describes the Window Manager routines that change a window’s display 
and position in the window list but not its size or location on the desktop. Note that the 
Window Manager automatically draws all visible windows on the screen. 


Your application typically uses only a few of the routines described in this section: 
DrawGrowlcon, SelectWindow, ShowWindow, and, occasionally, HideWindow. 


DrawGrowlcon 


DESCRIPTION 
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Use the DrawGrowIcon procedure to draw a window’s size box. 


PROCEDURE DrawGrowlIcon (theWindow: WindowPtr); 





theWindow A pointer to the window record. 


The DrawGrowIcon procedure draws a window’s size box or, if the window can’t be 
sized, whatever other image is appropriate. You call DrawGrowIcon when drawing the 
content region of a window that contains a size box. 


The exact appearance and location of the image depend on the window type and the 
window’s active or inactive state. The DrawGrowIcon procedure automatically checks 
the window’s type and state and draws the appropriate image. 
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In an active document window, DrawGrowIcon draws the grow image in the size box in 
the lower-right corner of the window’s graphics port rectangle, along with the lines 
delimiting the size box and scroll bar areas. To draw the size box but not the scroll bar 
outline, set the clipRgn field in the window’s graphics port to be a 15-by-15 pixel 
rectangle in the lower-right corner of the window. 


The DrawGrowIcon procedure doesn’t erase the scroll bar areas. If you use 
DrawGrowlIcon to draw the size box and scroll bar outline, therefore, you should 
erase those areas yourself when the window size changes, even if the window 
doesn’t contain scroll bars. 


In an inactive document window, DrawGrowIcon draws the lines delimiting the size 
box and scroll bar areas and erases the size box. 


See Listing 4-8 on page 4-39 for an example that draws a window’s content region, 
including the size box. See Listing 4-11 on page 4-51 for an example that calls 
DrawGrowlIcon to remove the size-box icon when a window becomes inactive. 


SelectWindow 


DESCRIPTION 


Use the SelectWindow procedure to make a window active. The SelectWindow 
procedure changes the active status of a window but does not affect its visibility. 


PROCEDURE SelectWindow (theWindow: WindowPtr) ; 


theWindow A pointer to the window’s window record. 


The SelectWindow procedure removes highlighting from the previously active 
window, brings the specified window to the front, highlights it, and generates the 
activate events to deactivate the previously active window and activate the specified 
window. If the specified window is already active, SelectWindow has no effect. 


Even if the specified window is invisible, SelectWindow brings the window to the 
front, activates the window, and deactivates the previously active window. Note that in 
this case, no active window is visible on the screen. If you do select an invisible window, 
be sure to call ShowWindow immediately to make the window visible (and accessible to 
the user). 


Call SelectWindow when the user presses the mouse button while the cursor is in the 
content region of an inactive window. 
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See Listing 4-9 on page 4-44 for an example that calls SelectWindow to change 
the active window when the user presses the mouse button while the cursor is 
in an inactive window. 


See Listing 4-18 on page 4-64 for an example that uses Select Window and 
ShowWindow together to restore a window’s active, visible status after it has 
been made invisible with HideWindow. 


ShowWindow 


DESCRIPTION 


SEE ALSO 
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Use the ShowWindow procedure to make an invisible window visible. 
PROCEDURE ShowWindow (theWindow: WindowPtr); 


theWindow A pointer to the window record of the window. 


The ShowWindow procedure makes an invisible window visible. If the specified window 
is already visible, ShowWindow has no effect. Your application typically creates a new 
window in an invisible state, performs any necessary setup of the content region, and 
then calls ShowWindow to make the window visible. 


When you display a previously invisible window by calling ShowWindow, the Window 
Manager draws the window frame and then generates an update event to trigger your 
application’s drawing of the content region. 


If the newly visible window is the frontmost window, ShowWindow highlights it if 
it’s not already highlighted and generates an activate event to make it active. The 
ShowWindow procedure does not activate a window that is not frontmost on the desktop. 


Note 

Because ShowWindow does not change the front-to-back ordering of 
windows, it is not the inverse of HideWindow. If you make the 
frontmost window invisible with HideWindow, and HideWindow has 
activated another window, you must call both ShowWindow and 
SelectWindow to bring the original window back to the front. 


See Listing 4-16 on page 4-60 for an example that temporarily hides a dialog box 
window when the user closes it. See Listing 4-18 on page 4-64 for the example that 
calls ShowWindow to display the window again later. 
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HideWindow 


DESCRIPTION 


SEE ALSO 


ShowHide 


DESCRIPTION 


Use the HideWindow procedure to make a window invisible. 





PROCEDURE HideWindow (theWindow: WindowPtr); 











theWindow A pointer to the window’s window record. 


The HideWindow procedure make a visible window invisible. If you hide the frontmost 
window, HideWindow removes the highlighting, brings the window behind it to 

the front, highlights the new frontmost window, and generates the appropriate 

activate events. 


To reverse the actions of HideWindow, you must call both ShowWindow, to make the 
window visible, and SelectWindow, to select it. 


See Listing 4-16 on page 4-60 for an example that calls HideWindow to temporarily 
hide a dialog box window when the user closes it. See Listing 4-18 on page 4-64 for the 
companion example that redisplays the window later. 


Use the ShowHide procedure to set a window’s visibility status. 
PROCEDURE ShowHide (theWindow: WindowPtr; showFlag: Boolean) ; 


theWindow A pointer to the window’s window record. 





showFlag A Boolean value that determines visibility status: TRUE makes a window 
visible; FALSE makes it invisible. 





The ShowHide procedure sets a window’s visibility to the status specified by the 
showF lag parameter. If the value of showFlag is TRUE, ShowHide makes the window 
visible if it’s not already visible and has no effect if it’s already visible. If the value of 
showF lag is FALSE, ShowHide makes the window invisible if it’s not already invisible 
and has no effect if it’s already invisible. 





The ShowHide procedure never changes the highlighting or front-to-back ordering of 
windows and generates no activate events. 
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WARNING 

Use this procedure carefully and only in special circumstances where 
you need more control than that provided by HideWindow and 
ShowWindow. Do not, for example, use ShowHide to hide the active 
window without making another window active. & 


HiliteWindow 


DESCRIPTION 


Use the HiliteWindow procedure to set a window’s highlighting status. 
PROCEDURE HiliteWindow (theWindow: WindowPtr; fHilite: Boolean); 


theWindow A pointer to the window’s window record. 


fHilite A Boolean value that determines the highlighting status: TRUE highlights 
a window; FALSE removes highlighting. 


The HiliteWindow procedure sets a window’s highlighting status to the specified state. 
If the value of the fHilite parameter is TRUE, HiliteWindow highlights the specified 
window; if the specified window is already highlighted, the procedure has no effect. 

If the value of fHilite is FALSE, HiliteWindow removes highlighting from the 
specified window; if the window is not already highlighted, the procedure has no effect. 








Your application doesn’t normally need to call HiliteWindow. To make a window 
active, you can call SelectWindow, which handles highlighting for you. 


BringToFront 


DESCRIPTION 
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Use the BringToFront procedure to bring a window to the front. 
PROCEDURE BringToFront (theWindow: WindowPtr) ; 


theWindow A pointer to the window’s window record. 


The BringToFront procedure puts the specified window at the beginning of the 
window list and redraws the window in front of all others on the screen. It does 
not change the window’s highlighting or make it active. 


Your application does not ordinarily call BringToFront. The user interface guidelines 
specify that the frontmost window should be the active window. To bring a window to 
the front and make it active, call the SelectWindow procedure. 
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SendBehind 


Use the SendBehind procedure to move one window behind another. 





PROCEDURE SendBehind (theWindow, behindWindow: WindowPtr) ; 











theWindow A pointer to the window to be moved. 


behindWindow 
A pointer to the window that is to be in front of the moved window. 


DESCRIPTION 


The SendBehind procedure moves the window pointed to by the parameter 
theWindow behind the window pointed to by the parameter behindWindow. If the 
move exposes previously obscured windows or parts of windows, SendBehind 
redraws the frames as necessary and generates the appropriate update events to 
have any newly exposed content areas redrawn. 











If the value of behindWindow is NIL, SendBehind sends the window to be moved 
behind all other windows on the desktop. If the window to be moved is the active 
window,SendBehind removes its highlighting, highlights the newly exposed frontmost 
window, and generates the appropriate activate events. 





Note 

Do not use SendBehind to deactivate a window after you’ve made a 
new window active with the SelectWindow procedure. The 
SelectWindow procedure automatically deactivates the previously 
active window. # 





Retrieving Window Information 
This section describes 


m the FindWindow function, which maps the cursor location of a mouse-down event to 
parts of the screen or regions of a window 


m the FrontWindow function, which tells your application which window is active 


FindWindow 


When your application receives a mouse-down event, call the FindWindow function to 
map the location of the cursor to a part of the screen or a region of a window. 


FUNCTION FindWindow (thePoint: Point; 
VAR theWindow: WindowPtr): Integer; 
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thePoint The point, in global coordinates, where the mouse-down event occurred. 
Your application retrieves this information from the where field of the 
event record. 

theWindow A parameter in which FindWindow returns a pointer to the window in 
which the mouse-down event occurred, if it occurred in a window. If it 
didn’t occur in a window, FindWindow sets theWindow toNIL. 


The FindWindow function returns an integer that specifies where the cursor was when 
the user pressed the mouse button. You typically call FindWindow whenever you 
receive a mouse-down event. The FindWindow function helps you dispatch the event by 
reporting whether the cursor was in the menu bar or in a window when the mouse 
button was pressed and, if it was in a window, which window and which region of the 
window. If the mouse-down event occurred in a window, FindWindow places a pointer 
to the window in the parameter theWindow. 


The FindWindow function returns an integer that specifies one of nine regions: 








CONST inDesk = 0; {none of the following} 

inMenuBar = 1; {in menu bar} 

inSysWindow = 2; {in desk accessory window} 

inContent = 3; {anywhere in content region except size } 
{ box if window is active, } 
{ anywhere including size box if window } 
{ is inactive} 

inDrag = 4; {in drag (title bar) region} 

inGrow = 5; {in size box (active window only) } 

inGoAway = 6; {in close box} 

inZoomIn = 7; {in zoom box (window in standard state) } 

inZoomOut = 8; {in zoom box (window in user state) } 


The FindWindow function returns inDesk if the cursor is not in the menu bar, a desk 
accessory window, or any window that belongs to your application. The FindWindow 
function might return this value if, for example, the user presses the mouse button while 
the cursor is on the window frame but not in the title bar, close box, or zoom box. When 
F indWindow returns inDesk, your application doesn’t need to do anything. In System 
7, when the user presses the mouse button while the cursor is on the desktop or ina 
window that belongs to another application, the Event Manager sends your application 
a suspend event and switches to the Finder or another application. 


The FindWindow function returns inMenuBar when the user presses the mouse button 
with the cursor in the menu bar. Your application typically adjusts its menus and then 
calls the Menu Manager’s function MenuSelect to let the user choose menu items. 


The FindWindow function returns inSysWindow when the user presses the mouse 
button while the cursor is in a window belonging to a desk accessory that was launched 
in your application’s partition. This situation seldom arises in System 7. When the user 
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clicks in a window belonging to a desk accessory launched independently, the Event 
Manager sends your application a suspend event and switches to the desk accessory. 


If FindWindow does return inSysWindow, your application calls the SystemClick 
procedure, documented in the chapter “Event Manager” in this book. The 
SystemClick procedure routes the event to the desk accessory. If the user presses 

the mouse button with the cursor in the content region of an inactive desk 

accessory window, SystemClick makes the window active by sending your applica- 
tion and the desk accessory the appropriate activate events. 


The FindWindow function returns inContent when the user presses the mouse button 
with the cursor in the content area (excluding the size box in an active window) of one of 
your application’s windows. Your application then calls its routine for handling clicks in 
the content region. 


The FindWindow function returns inDrag when the user presses the mouse button 
with the cursor in the drag region of a window (that is, the title bar, excluding the close 
box and zoom box). Your application then calls the Window Manager’s DragWindow 
procedure to let the user drag the window to a new location. 


The FindWindow function returns inGrow when the user presses the mouse button 
with the cursor in an active window’s size box. Your application then calls its own 
routine for resizing a window. 


The FindWindow function returns inGoAway when the user presses the mouse 
button with the cursor in an active window’s close box. Your application calls the 
TrackGoAway function to track mouse activity while the button is down and then 
calls its own routine for closing a window if the user releases the button while the 
cursor is in the close box. 


The FindWindow function returns inZoomIn or inZoomOut when the user presses the 
mouse button with the cursor in an active window’s zoom box. Your application calls the 
TrackBox function to track mouse activity while the button is down and then calls its 
own routine for zooming a window if the user releases the button while the cursor is in 
the zoom box. 


SEE ALSO 
See Listing 4-9 on page 4-44 for an example that calls FindWindow to determine the 
location of the cursor and then dispatches the mouse-down event depending on 
the results. 

FrontWindow 


Use the FrontWindow function to find out which window is active. 


FUNCTION FrontWindow: WindowPtr; 
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The FrontWindow function returns a pointer to the first visible window in the 
window list (that is, the active window). If there are no visible windows, FrontWindow 
returns NIL. 


See Listing 4-9 on page 4-44 for an example that calls FrontWindow to determine 
whether an event occurred in the active window. 


See Listing 4-12 on page 4-55 for an example that calls FrontWindow to determine 
whether to display a window in front of other windows after changing its size. 


See Listing 4-16 on page 4-60 and Listing 4-17 on page 4-61 for examples that call 
FrontWindow to determine which window is affected by a user command directed 
at the active window. 


Moving Windows 


This section describes the procedures that move windows on the desktop. 


To move a window, your application ordinarily needs to call only the DragWindow 
procedure, which itself calls the DragGrayRgn function, and the MoveWindow 
procedure. The DragGrayRgn function drags a dotted outline of the window on the 
screen, following the motion of the cursor, as long as the user holds down the mouse 
button. The DragGrayRgn function itself calls the PinRect function to contain the 
point where the cursor was when the mouse button was first pressed inside the 
available desktop area. When the user releases the mouse button, DragWindow calls 
MoveWindow, which moves the window to a new location. 


DragWindow 
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When the user drags a window by its title bar, use the DragWindow procedure to move 
the window on the screen. 








PROCEDURE DragWindow (theWindow: WindowPtr; 
startPt: Point; boundsRect: Rect); 








theWindow A pointer to the window record of the window to be dragged. 


startPt The location, in global coordinates, of the cursor at the time the user 
pressed the mouse button. Your application retrieves this point from the 
where field of the event record. 
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boundsRect A rectangle, in global coordinates, that limits the region to which a 
window can be dragged. If the mouse button is released when the 
cursor is outside the limits of boundsRect, DragWindow returns 
without moving the window (or, if it was inactive, without making 
it the active window). 


Because the user cannot ordinarily move the cursor off the desktop, 
you can safely set boundsRect to the largest available rectangle (the 
bounding box of the desktop region pointed to by the global variable 
GrayRgn) when you're using DragWindow to track mouse movements. 
Don’t set the bounding rectangle to the size of the immediate screen 
(screenBits.bounds), because the user wouldn’t be able to move 
the window to a different screen on a system equipped with 

multiple monitors. 





The DragWindow procedure moves a dotted outline of the specified window around the 
screen, following the movement of the cursor until the user releases the mouse button. 
When the button is released, DragWindow calls MoveWindow to move the window to its 
new location. If the specified window isn’t the active window (and the Command key 
wasn’t down when the mouse button was pressed), DragWindow makes it the active 
window by setting the front parameter to TRUE when calling MoveWindow. If the 
Command key was down when the mouse button was pressed, DragWindow moves the 
window without making it active. 





The DragWindow procedure calls both MoveWindow and DragGrayRgn, which are 
described in this section. 


See Listing 4-9 on page 4-44 for an example that calls DragWindow when the user 
presses the mouse button while the cursor is in the drag region. 


MoveWindow 


Use the MoveWindow procedure to move a window on the desktop. 


PROCEDURE MoveWindow (theWindow: WindowPtr; 
hGlobal, vGlobal: Integer; 
front: Boolean); 








theWindow A pointer to the window record of the window being moved. 


hGlobal The new location, in global coordinates, of the left edge of the window’s 
port rectangle. 


vGlobal The new location, in global coordinates, of the top edge of the window’s 
port rectangle. 
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front A Boolean value specifying whether the window is to become the 
frontmost, active window. If the value of the front parameter is FALSE, 
MoveWindow does not change its plane or status. If the value of the front 
parameter is TRUE and the window isn’t active, MoveWindow makes it 
active by calling the SelectWindow procedure. 








The MoveWindow procedure moves the specified window to the location specified by the 
hGlobal and vGlobal parameters, without changing the window’s size. The upper-left 
corner of the window’s port rectangle is placed at the point (vGlobal,hGlobal). The 
local coordinates of the upper-left corner are unaffected. 


Your application doesn’t normally call MoveWindow. When the user drags a window by 
dragging its title bar, you can call DragWindow, which in turn calls MoveWindow when 
the user releases the mouse button. 


DragGrayRgn 
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The DragWindow function calls the DragGrayRgn function to move an outline of a 
window around the screen as the user drags a window. 


FUNCTION DragGrayRgn (theRgn: RgnHandle; startPt: Point; 
limitRect, slopRect: Rect; axis: Integer; 
actionProc: ProcPtr): LongInt; 


theRgn A handle to the region to be dragged. 


startPt The location, in the local coordinates of the current graphics port, of the 
cursor when the mouse button was pressed. 


limitRect A rectangle, in the local coordinates of the current graphics port, that 
limits where the region can be dragged. This parameter works in 
conjunction with the slopRect parameter, as illustrated in Figure 4-23 
on page 4-98. 

slopRect A rectangle, in the local coordinates of the current graphics port, that 
gives the user some leeway in moving the mouse without violating 
the limits of the limitRect parameter, as illustrated in Figure 4-23 on 
page 4-98. The slopRect rectangle should be larger than the limitRect 
rectangle. 


axis A constant that constrains the region’s motion. The axis parameter can 
have one of these values: 


CONST noConstraint 0; {no constraints} 
hAxisOnly 


ll 
bh 
~ 


{move on horizontal axis } 
{ only} 
{move on vertical axis } 


ll 
i) 
~ 


vAxisOnly 
{ only} 
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If an axis constraint is in effect, the outline follows the cursor’s 
movements along only the specified axis, ignoring motion along the other 
axis. With or without an axis constraint, the outline appears only when 
the mouse is inside the slopRect rectangle. 


actionProc A pointer to a procedure that defines an action to be performed 
repeatedly as long as the user holds down the mouse button. The 
procedure can have no parameters. If the value of actionProc is NIL, 
DragGrayRgn simply retains control until the mouse button is released. 


The DragGrayRgn function moves a gray outline of a region on the screen, following 

the movements of the cursor, until the mouse button is released. It returns the difference 
between the point where the mouse button was pressed and the offset point—that is, the 
point in the region whose horizontal and vertical offsets from the upper-left corner of the 
region’s enclosing rectangle are the same as the offsets of the starting point when the 
user pressed the mouse button. The DragGrayRgn function stores the vertical difference 
between the starting point and the offset point in the high-order word of the return value 
and the horizontal difference in the low-order word. 


The DragGrayRgn function limits the movement of the region according to the 
constraints set by the limitRect andslopRect parameters: 


m As long as the cursor is inside the limitRect rectangle, the region’s outline follows 
it normally. If the mouse button is released while the cursor is within this rectangle, 
the return value reflects the simple distance that the cursor moved in each dimension. 


m When the cursor moves outside the limitRect rectangle, the offset point stops at the 
edge of the limitRect rectangle. If the mouse button is released while the cursor 
is outside the limitRect rectangle but inside the slopRect rectangle, the return 
value reflects only the difference between the starting point and the offset point, 
regardless of how far outside of the LimitRect rectangle the cursor may have 
moved. (Note that part of the region can fall outside the limitRect rectangle, but 
not the offset point.) 


m When the cursor moves outside the slopRect rectangle, the region’s outline 
disappears from the screen. The DragGrayRgn function continues to track the cursor, 
however, and if the cursor moves back into the slopRect rectangle, the outline 
reappears. If the mouse button is released while the cursor is outside the slopRect 
rectangle, both words of the return value are set to $8000. In this case, the Window 
Manager does not move the window from its original location. 


Figure 4-23 on page 4-98 illustrates how the region stops moving when the offset point 
reaches the edge of the LimitRect rectangle. The cursor continues to move, but the 
region does not. 


If the mouse button is released while the cursor is anywhere inside the slopRect 
rectangle, the Window Manager redraws the window in its new location, which is 
calculated from the value returned by DragGrayRgn. 
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Figure 4-23 Limiting rectangle used by DragGrayRgn 
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ASSEMBLY-LANGUAGE INFORMATION 


You can set the global variable DragHook to point to an optional procedure, defined 
by your application, which will be called by DragGrayRgn as long as the mouse 
button is held down. (If there’s an actionProc procedure, it is called first.) If you 
want DragGrayRgn to draw the region’s outline in a pattern other than gray, you 
can store the pattern in the global variable DragPattern and then invoke the macro 
_DragTheRgn. Note that the use of the Window Manager’s global variables is not 
guaranteed to be compatible with system software versions later than System 6. 
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The DragGrayRgn function uses the PinRect function to contain a point within a 
specified rectangle. 


FUNCTION PinRect (theRect: Rect; thePt: Point): LongInt; 


theRect The rectangle in which the point is to be contained. 


thePt The point to be contained. 


The PinRect function returns a point within the specified rectangle that is as close as 
possible to the specified point. (The high-order word of the returned long integer is the 
vertical coordinate; the low-order word is the horizontal coordinate.) 


If the specified point is within the rectangle, PinRect returns the point itself. If not, then 


m if the horizontal position is to the left of the rectangle, PinRect returns the left edge 
as the horizontal coordinate 


m if the horizontal position is to the right of the rectangle, PinRect returns the right 
edge minus 1 as the horizontal coordinate 


m if the vertical position is above the rectangle, PinRect returns the top edge as the 
vertical coordinate 


m if the vertical position is below the rectangle, PinRect returns the bottom edge minus 
1 as the vertical coordinate 


Note 

The 1 is subtracted when the point is below or to the right of the 
rectangle so that a pixel drawn at that point lies within the rectangle. If 
the point is exactly on the bottom or the right edge of the rectangle, 
however, 1 should be subtracted but isn’t. # 


Resizing Windows 


This section describes the procedures you can use to track the cursor while the user 
resizes a window and to draw the window in a new size. 


GrowWindow 


Use the GrowWindow function to allow the user to change the size of a window. The 
GrowWindow function displays an outline (grow image) of the window as the user 
moves the cursor to make the window larger or smaller; it handles all user interaction 
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until the user releases the mouse button. After calling GrowWindow, you call the 
SizeWindow procedure to change the size of the window. 


FUNCTION GrowWindow (theWindow: WindowPtr; 
startPt: Point; sizeRect: Rect): LongInt; 


theWindow A pointer to the window record of the window to drag. 


startPt The location of the cursor at the time the mouse button was first pressed, 
in global coordinates. Your application retrieves this point from the 
where field of the event record. 


sizeRect The limits on the vertical and horizontal measurements of the port 
rectangle, in pixels. 
Although the sizeRect parameter is in the form of the Rect data 
type, the four numbers in the structure represent lengths, not 
screen coordinates. The top, left, bottom, and right fields of the 
sizeRect parameter specify the minimum vertical measurement 
(top), the minimum horizontal measurement (left), the maximum 
vertical measurement (bottom), and the maximum horizontal 
measurement (right). 
The minimum measurements must be large enough to allow a 
manageable rectangle; 64 pixels on a side is typical. Because the user 
cannot ordinarily move the cursor off the screen, you can safely set 
the upper bounds to the largest possible length (65,535 pixels) when 
you're using GrowWindow to follow cursor movements. 


The GrowWindow function moves a dotted-line image of the window’s right and lower 
edges around the screen, following the movements of the cursor until the mouse button 
is released. It returns the new dimensions, in pixels, of the resulting window: the height 
in the high-order word of the returned long-integer value and the width in the low-order 
word. You can use the functions HiWord and LoWord to retrieve only the high-order and 
low-order words, respectively. 


A return value of 0 means that the new size is the same as the size of the current 
port rectangle. 
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You can set the global variable DragHook to point to an optional procedure, defined by 
your application, which will be called by GrowWindow as long as the mouse button is 
held down. (If there’s an actionProc procedure, the act ionProc procedure is called 
first.) Note that the use of the Window Manager’s global variables is not guaranteed to 
be compatible with system software versions later than System 6. 


See Listing 4-13 on page 4-58 for an example that calls GcowWindow when the user 
presses the mouse button while the cursor is in the size box. 
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SizeWindow 


DESCRIPTION 


SEE ALSO 


Use the SizeWindow procedure to set the size of a window. 











PROCEDURE SizeWindow (theWindow: WindowPtr; w, h: Integer; 
fUpdate: Boolean) ; 








theWindow A pointer to the window record of the window to be sized. 


w The new window width, in pixels. 
h The new window height, in pixels. 
fUpdate A Boolean value that specifies whether any newly created area of the 





content region is to be accumulated into the update region (TRUE) or not 
(FALSE). You ordinarily pass a value of TRUE to ensure that the area is 
updated. If you pass FALSE, you're responsible for maintaining the 
update region yourself. For more information on adding rectangles to and 
removing rectangles from the update region, see the description of 
InvalRect on page 4-107 and ValidRect on page 4-108. 





The SizeWindow procedure changes the size of the window’s graphics port rectangle to 
the dimensions specified by the w and h parameters, or does nothing if the values of w 
and h are 0. The Window Manager redraws the window in the new size, recentering the 
title and truncating it if necessary. Your application calls SizeWindow immediately after 
calling GrowWindow, to adjust the window to any changes made by the user through the 
size box. 


See Listing 4-13 on page 4-58 for an example that calls Si zeWindow to resize a window 
based on the return value of GrowWindow. 


Zooming Windows 


TrackBox 


This section describes the procedures you can use to track mouse activity in the zoom 
box and to zoom windows. 





Use the TrackBox function to track the cursor when the user presses the mouse button 
while the cursor is in the zoom box. 


FUNCTION TrackBox (theWindow: WindowPtr; thePt: Point; 


partCode: Integer): Boolean; 
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theWindow A pointer to the window record of the window in which the mouse 
button was pressed. 

thePt The location of the cursor when the mouse button was pressed. Your 
application receives this point from the where field in the event record. 


partCode The part code (either inZoomIn or inZoomOut) returned by the 
F indWindow function. 


The TrackBox function tracks the cursor when the user presses the mouse button while 
the cursor is in the zoom box, retaining control until the mouse button is released. While 
the button is down, TrackBox highlights the zoom box while the cursor is in the zoom 
region, as illustrated in Figure 4-20 on page 4-47. 





When the mouse button is released, TrackBox removes the highlighting from the zoom 
box and returns TRUE if the cursor is within the zoom region and FALSE if it is not. 








Your application calls the TrackBox function when it receives a result code of either 
inZoomIn or inZoomOut from the FindWindow function. If TrackBox returns TRUE, 
your application calculates the standard state, if necessary, and calls the ZoomWindow 
procedure to zoom the window. If TrackBox returns FALSE, your application 

does nothing. 











ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 


You can set the global variable DragHook to point to an optional procedure, defined by 
your application, which will be called by TrackBox as long as the mouse button is held 
down. (If there’s an act ionProc procedure, the act ionProc procedure is called first.) 
Note that the use of the Window Manager’s global variables is not guaranteed to be 
compatible with system software versions later than System 6. 


See Listing 4-12 on page 4-55 for an example that calls TrackBox to track cursor activity 
when the user presses the mouse button while the cursor is in the zoom box. 


ZoomWindow 
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Use the ZoomWindow procedure to zoom the window when the user has pressed and 
released the mouse button with the cursor in the zoom box. 


PROCEDURE ZoomWindow (theWindow: WindowPtr; 
partCode: Integer; front: Boolean); 





theWindow A pointer to the window record of the window to be zoomed. 


partCode The result (either inZoomIn or inZoomOut) returned by the 
F indWindow function. 
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front A Boolean value that determines whether the window is to be brought to 
the front. If the value of front is TRUE, the window necessarily becomes 
the frontmost, active window. If the value of front is FALSE, the 
window’s position in the window list does not change. Note that if a 
window was active before it was zoomed, it remains active even if the 
value of front is FALSE. 











The ZoomWindow procedure zooms a window in or out, depending on the value of 

the part Code parameter. Your application calls ZoomWindow, passing it the part 
code returned by FindWindow, when it receives a result of TRUE from TrackBox. 

The ZoomWindow procedure then changes the window’s port rectangle to either 

the user state (if the part code is inZoomIn) or the standard state (if the part code is 
inZoomOut), as stored in the window state data record, described in the section 
“Zooming a Window” beginning on page 4-53. 





If the part code is inZoomOut, your application ordinarily calculates and sets the 
standard state before calling ZoomWindow. 


For best results, call the QuickDraw procedure EraseRect, passing the window’s 
graphics port as the port rectangle, before calling ZoomWindow. 


See Listing 4-12 on page 4-55 for an example that calculates and sets the standard state 
and then calls ZoomWindow to zoom a window. 


Closing and Deallocating Windows 


This section describes the procedures that track user activity in the close box and that 
close and dispose of windows. 


When you no longer need a window, call the CloseWindow procedure if you 
allocated the memory for the window record or the DisposeWindow procedure if 
you did not. 


TrackGoAway 


Use the TrackGoAway function to track the cursor when the user presses the mouse 
button while the cursor is in the close box. 


FUNCTION TrackGoAway (theWindow: WindowPtr; 
thePt: Point): Boolean; 





theWindow A pointer to the window record of the window in which the mouse-down 
event occurred. 


thePt The location of the cursor at the time the mouse button was pressed. Your 
application receives this point from the where field of the event record. 
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The TrackGoAway function tracks cursor activity when the user presses the mouse 
button while the cursor is in the close box, retaining control until the user releases the 
mouse button. While the button is down, TrackGoAway highlights the close box as long 
as the cursor is in the close region, as illustrated in Figure 4-19 on page 4-46. 


When the mouse button is released, TrackGoAway removes the highlighting from the 
close box and returns TRUE if the cursor is within the close region and FALSE if it is not. 








Your application calls the TrackGoAway function when it receives a result code of 
inGoAway from the FindWindow function. If TrackGoAway returns TRUE, your 
application calls its own procedure for closing a window, which can call either the 
CloseWindow procedure or the DisposeWindow procedure to remove the window 
from the screen. (Before removing a document window, your application ordinarily 
checks whether the document has changed since the associated file was last saved. 

See the chapter “Introduction to File Management” in Inside Macintosh: Files for a 
general discusion of handling files.) If TrackGoAway returns FALSE, your application 
does nothing. 





ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 


You can set the global variable DragHook to point to an optional procedure, defined by 
your application, which will be called by TrackGoAway as long as the mouse button is 
held down. (If there’s an actionProc procedure, the act ionProc procedure is called 
first.) Note that the use of the Window Manager’s global variables is not guaranteed to 
be compatible with system software versions later than System 6. 


See Listing 4-9 on page 4-44 for an example that calls TrackGoAway to track cursor 
activity when the user presses the mouse button while the cursor is in the close box. 


CloseWindow 


DESCRIPTION 
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Use the CloseWindow procedure to remove a window if you allocated memory yourself 
for the window’s window record. 


PROCEDURE CloseWindow (theWindow: WindowPtr); 


theWindow A pointer to the window record of the window to be closed. 


The CloseWindow procedure removes the specified window from the screen and 
deletes it from the window list. It releases the memory occupied by all data structures 
associated with the window except the window record itself. 
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If you allocated memory for the window record and passed a pointer to it as one of the 
parameters to the functions that create windows, call CloseWindow when you're done 
with the window. You must then call the Memory Manager procedure DisposePtr to 
release the memory occupied by the window record. 


WARNING 

If your application allocated any other memory for use with a window, 
you must release it before calling CloseWindow. The Window Manager 
releases only the data structures it created. 


Also, CloseWindow assumes that any picture pointed to by the window 
record field windowPic is data, not a resource, and it calls the 
QuickDraw procedure Kil1Picture to delete it. If your application 
uses a picture stored as a resource, you must release the memory it 
occupies with the ReleaseResource procedure and set the 
windowPic field to NIL before closing the window. « 


Any pending update events for the window are discarded. If the window being removed 
is the frontmost window, the window behind it, if any, becomes the active window. 


See Listing 4-17 on page 4-61 for an example that calls CloseWindow to remove a 
window from the screen. 


See Listing 4-3 on page 4-28 for an example that calls CloseWindow to clean up memory 
when an attempt to create a new window fails. 


DisposeWindow 


DESCRIPTION 


Use the DisposeWindow procedure to remove a window if you let the Window 
Manager allocate memory for the window record. 


PROCEDURE DisposeWindow (theWindow: WindowPtr) ; 





theWindow A pointer to the window record of the window to be closed. 


The DisposeWindow procedure removes a window from the screen, deletes it from the 
window list, and releases the memory occupied by all structures associated with the 
window, including the window record. (DisposeWindow calls CloseWindow and then 
releases the memory occupied by the window record.) 
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WARNING 

If your application allocated any other memory for use with a window, 
you must release it before calling DisposeWindow. The Window 
Manager releases only the data structures it created. 


The DisposeWindow procedure assumes that any picture pointed to by 
the window record field windowPic is data, not a resource, and it calls 
the QuickDraw procedure Kil1Picture to delete it. If your application 
uses a picture stored as a resource, you must release the memory it 
occupies with the ReleaseResource procedure and set the 
windowPic field to NIL before closing the window. « 





Any pending update events for the window are discarded. If the window being removed 
is the frontmost window, the window behind it, if any, becomes the active window. 


Maintaining the Update Region 


This section describes the routines you use to update your windows and to maintain 
window update regions. 


BeginUpdate 


DESCRIPTION 
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Use the BeginUpdate procedure to start updating a window when you receive an 
update event for that window. 





PROCEDURE BeginUpdate (theWindow: WindowPtr) ; 














theWindow A pointer to the window’s window record. Your application gets this 
information from the message field in the update event record. 


The BeginUpdate procedure limits the visible region of the window’s graphics port to 
the intersection of the visible region and the update region; it then sets the window’s 
update region to an empty region. After calling BeginUpdate, your application redraws 
either the entire content region or only the visible region. In either case, only the parts of 
the window that require updating are actually redrawn on the screen. 





Every call to BeginUpdate must be matched with a subsequent call to EndUpdate after 
your application redraws the content region. 


Note 
In Pascal, BeginUpdate and EndUpdate can’t be nested. That is, 
you must call EndUpdate before the next call to BeginUpdate. 














You can nest BeginUpdate and EndUpdate calls in assembly 
language if you save and restore the copy of the visRgn, a copy 
of which is stored, in global coordinates, in the global variable 
SaveVisRgn. 
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SPECIAL CONSIDERATIONS 


SEE ALSO 


EndUpdate 


DESCRIPTION 


SEE ALSO 


InvalRect 


If you don’t clear the update region when you receive an update event, the Event 
Manager continues to send update events until you do. 


See Figure 4-21 on page 4-49 for an illustration of how BeginUpdate and EndUpdate 
affect the visible region and update region. See Listing 4-10 on page 4-50 for an example 
that updates a window. 





Use the EndUpdate procedure to finish updating a window. 

















PROCEDURE EndUpdate (theWindow: WindowPtr) ; 


theWindow A pointer to the window’s window record. 


The EndUpdate procedure restores the normal visible region of a window’s graphics 
port. When you receive an update event for a window, you call BeginUpdate, redraw 
the update region, and then call EndUpdate. Each call to BeginUpdate must be 
balanced by a subsequent call to EndUpdate. 











See Figure 4-21 on page 4-49 for an illustration of how BeginUpdate and EndUpdate 
affect the visible region and update region. See Listing 4-10 on page 4-50 for an example 
that updates a window. 


Use the InvalRect procedure to add a rectangle to a window’s update region. 





PROCEDURE InvalRect (badRect: Rect); 











badRect A rectangle, in local coordinates, that is to be added to a window’s 
update region. 
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The InvalRect procedure adds a specified rectangle to the update region of the 
window whose graphics port is the current port. Specify the rectangle in local 
coordinates. The Window Manager clips it, if necessary, to fit in the window’s 
content region. 


Both your application and the Window Manager use the InvalRect procedure. 

When the user enlarges a window, for example, the Window Manager uses InvalRect 
to add the newly created content region to the update region. Your application uses 
InvalRect to add the two rectangles formerly occupied by the scroll bars in the smaller 
content area. 


Use the InvalRgn procedure to add a region to a window’s update region. 
PROCEDURE InvalRgn (badRgn: RgnHandle) ; 


badRgn The region, in local coordinates, that is to be added to a window’s 
update region. 


The InvalRgn procedure adds a specified region to the update region of the window 
whose graphics port is the current port. Specify the region in local coordinates. The 
Window Manager clips it, if necessary, to fit in the window’s content region. 


See Listing 4-13 on page 4-58 for an example that uses InvalRgn to add part of the 
window’s content region to the update region. 


Use the ValidRect procedure to remove a rectangle from a window’s update region. 





PROCEDURE ValidRect (goodRect: Rect); 











goodRect A rectangle, in local coordinates, to be removed from a window’s 
update region. 
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The ValidRect procedure removes a specified rectangle from the update region of the 
window whose graphics port is the current port. Specify the region in local coordinates. 
The Window Manager clips it, if necessary, to fit in the window’s content region. 


Your application uses ValidRect to tell the Window Manager that it has already drawn 
a rectangle and to cancel any updates accumulated for that area. You can thereby 
improve response time by reducing redundant redrawing. 


Suppose, for example, that you’ve resized a window that contains a size box and 

scroll bars. Depending on the dimensions of the newly sized window, the new size 

box and scroll bar areas may or may not have been accumulated into the window’s 
update region. After calling Si zeWindow, you can redraw the size box or scroll bars 
immediately and then call ValidRect for the areas they occupy. If they were in fact 
accumulated into the update region, ValidRect removes them so that you do not have 
to redraw them with the next update event. 


See Listing 4-13 on page 4-58 for an example that uses ValidRect to remove part of the 
window’s content region from the update region. 


Use the ValidRgn procedure to remove a specified region from a window’s 
update region. 





PROCEDURE ValidRgn (goodRgn: RgnHandle) ; 











goodRgn A region, in local coordinates, to be removed from a window’s 
update region. 


The ValidRgn procedure removes a specified region from the update region of the 
window whose graphics port is the current port. Specify the region in local coordinates. 
The Window Manager clips it, if necessary, to fit in the window’s content region. 


Setting and Retrieving Other Window Characteristics 


This section describes the routines that let you set and retrieve less commonly used fields 
in the window record. 
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SetWindowPic 


DESCRIPTION 


Use the SetWindowPic procedure to establish a picture that the Window Manager can 
draw in a window’s content region. 


PROCEDURE SetWindowPic (theWindow: WindowPtr; 
Pic: PicHandle); 


theWindow A pointer to a window’s window record. 


Pic A handle to the picture to be drawn in the window. 


The SetWindowPic procedure stores in a window’s window record a handle to a 

picture to be drawn in the window. When the window’s content region must be updated, 
the Window Manager then draws the picture or part of the picture, as necessary, instead 
of generating an update event. 


Note 

The CloseWindow and DisposeWindow procedures assume that any 
picture pointed to by the window record field windowPic is stored as 
data, not as a resource. If your application uses a picture stored as a 
resource, you must release the memory it occupies by calling the 
Resource Manager’s Re leaseResource procedure and set the 
WindowPic field to NIL before you close the window. # 





GetWindowPic 


DESCRIPTION 
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Use the Get WindowPic function to retrieve a handle to a window’s picture. 
FUNCTION GetWindowPic (theWindow: WindowPtr): PicHandle; 


theWindow A pointer to the window’s window record. 


The GetWindowPic function returns a handle to the picture to be drawn ina specified 
window’s content region. The handle must have been stored previously with the 
SetWindowPic procedure. 
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SetWRefCon 


DESCRIPTION 


SEE ALSO 


Use the SetWRefCon procedure to set the refCon field of a window record. 





PROCEDURE SetWRefCon (theWindow: WindowPtr; data: LongInt); 











theWindow A pointer to the window’s window record. 


data The data to be placed in the refCon field. 


The SetWRefCon procedure places the specified data in the refCon field of the 
specified window record. The refCon field is available to your application for any 
window-related data it needs to store. 


See Listing 4-3 on page 4-28 for an example that sets the refCon field. See Listing 4-16 
on page 4-60 for an example that uses the contents of the refCon field. 


GetWRefCon 


DESCRIPTION 


SEE ALSO 


Use the Get WRefCon function to retrieve the reference constant from a window’s 
window record. 


FUNCTION GetWRefCon (theWindow: WindowPtr): LongInt; 


theWindow A pointer to the window’s window record. 


The GetWRefCon function returns the long integer data stored in the refCon field of the 
specified window record. 


See the section “Managing Multiple Windows” beginning on page 4-23 for suggested 
ways to use the refCon field. See Listing 4-1 on page 4-25 for an example of an 
application-defined routine that gets the refCon field. 
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GetWVariant 


DESCRIPTION 


SEE ALSO 


Use the GetWVariant function to retrieve a window’s variation code. 
FUNCTION GetWVariant (theWindow: WindowPtr): Integer; 


theWindow A pointer to the window’s window record. 


The GetWVariant function returns the variation code of the specified window. 
Depending on the window’s window definition function, the result of GetWVariant 
can represent one of the standard window types listed in the section “Creating a 
Window” beginning on page 4-25 or a variation code defined by your own window 
definition function. 


See “Types of Windows” beginning on page 4-8 for a definition of variation codes. See 
“The Window Definition Function” beginning on page 4-120 for a detailed description of 
variation codes. 


Manipulating the Desktop 


This section describes the routines that let your application retrieve information about 
the desktop and set the desktop pattern. Ordinarily, your application doesn’t need to 
manipulate any part of the desktop outside of its own windows. 


SetDeskCPat 


DESCRIPTION 
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Use the SetDeskCPat procedure to set the desktop pattern on a computer that supports 
Color QuickDraw. 


PROCEDURE SetDeskCPat (deskPixPat: PixPatHandle); 





deskPixPat A handle to a pixel pattern. 


The SetDeskCPat procedure sets the desktop pattern to a specified pixel pattern, which 
can be drawn in more than two colors. After a call to SetDeskCPat, the desktop is 
automatically redrawn in the new pattern. If the specified pattern is a binary pattern 
(with a pattern type of 0), it is drawn is the current foreground and background colors. If 
the value of the deskPixPat parameter is NIL, SetDeskCPat uses the standard binary 
desk pattern (that is, the 'ppat' resource with resource ID 16). 
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Note 

For compatibility with other Macintosh applications and the 
system software, applications should ordinarily not change the 
desktop pattern. 


The Window Manager’s desktop-painting routines can paint the desktop either in the 
binary pattern stored in the global variable DeskPattern or ina new pixel pattern. The 
desktop pattern used at startup is determined by the value of the parameter-RAM bit 
flag called pCDeskPat. If the value of pCDeskPat is 0, the Window Manager uses the 
new pixel pattern; if not, it uses the binary pattern stored in DeskPattern. The user can 
change the color pattern through the General Controls panel, which changes the value 

of pCDeskPat. 


GetGrayRgn 


DESCRIPTION 


SEE ALSO 


Use the Get GrayRgn function to retrieve a handle to the current desktop region. 


FUNCTION GetGrayRgn: RgnHandle; 


The Get GrayRgn function returns a handle to the current desktop region from the 
global variable GrayRgn. 


The desktop region represents all available screen space, that is, the desktop area 
displayed by all monitors attached to the computer. Ordinarily, your application 
doesn’t need to access the desktop region directly. 


When your application calls DragWindow to let the user drag a window, it can use 
GetGrayRgn to set the limiting rectangle to the entire desktop area. 


See Listing 4-9 on page 4-44 for an example that uses Get GrayRgn to specify the 
limiting rectangle when calling DragWindow to let the user move a window. 


GetCWMerPort 


Use the Get CWMgrPort procedure to retrieve a pointer to the Window Manager port on 
a system that supports Color QuickDraw. 


PROCEDURE GetCWMgrPort (VAR wMgrCPort: CGrafPtr); 





wMgrCPort A parameter in which GetCWMgrPort returns a pointer to the Window 
Manager port. 
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DESCRIPTION 


The Get CWMgrPort procedure places a pointer to the color Window Manager port in 
the parameter wMgrCPort. The Get CWMgrPort procedure is available only on 
computers with Color QuickDraw. 


The Window Manager port is a graphics port that occupies all of the main screen. 
Ordinarily, your application doesn’t need to access the Window Manager port. 


Note 
Do not change any regions of the Window Manager port. If you do, the 
Window Manager might not handle overlapping windows properly. 


GetWMegrPort 


Use the Get WMgrPort procedure to retrieve a pointer to the Window Manager port ona 
system with only the original monochrome QuickDraw. 





PROCEDURE GetWMgrPort (VAR wPort: GrafPtr); 











wPort A parameter in which GetWMgrPort returns a pointer to the Window 
Manager port. 


DESCRIPTION 
The GetWMgrPort procedure places a pointer to the Window Manager port in the 
parameter wPort. 


The Window Manager port is a graphics port that occupies all of the main screen. 
Ordinarily, your application doesn’t need to access the Window Manager port. 


Note 


Do not change any regions of the Window Manager port. If you do, the 
Window Manager might not handle overlapping windows properly. 


Manipulating Window Color Information 


This section describes the routines you use for setting and retrieving window color 
information. Your application does not normally change window color information. 


SetWinColor 


Use the SetWinColor procedure to set a window’s window color table. 


PROCEDURE SetWinColor (theWindow: WindowPtr; 
newColorTable: WCTabHandle) ; 
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theWindow A pointer to the window’s window record. 
newColorTable 


A handle to a window color table record, which defines the colors for the 
window’s new color table. 


The SetWinColor procedure sets a window’s color table. If the window has no 
auxiliary window record, it creates a new one with the specified window color table and 
adds it to the auxiliary window list. If the window already has an auxiliary record, its 
window color table is replaced. The Window Manager then redraws the window frame 
and highlighted text in the new colors and sets the window’s background color to the 
new content color. 


If the new color table has the same entries as the default color table, SetWinColor 
changes the auxiliary window record so that it points to the default color table. 


Window color table resources (resources of type 'wctb') should not be purgeable. 


If you specify a value of NIL for the parameter theWindow, SetWinColor changes the 
default color table in memory. Your application shouldn't, however, change the default 
color table. 


For a description of a window color table, see “The Window Color Table Record” on 
page 4-71. For a description of the auxiliary window record, see “The Auxiliary Window 
Record” on page 4-73. For a description of the 'wctb' resource, see “The Window Color 
Table Resource” on page 4-127. 


Use the Get AuxWin function to retrieve a handle to a window’s auxiliary 
window record. 


FUNCTION GetAuxWin (theWindow: WindowPtr; 
VAR awHndl: AuxWinHandle): Boolean; 
theWindow A pointer to the window’s window record. 


awHndl A handle to the window’s auxiliary window record. 


The Get AuxWin function returns a Boolean value that reports whether or not the 
window has an auxiliary window record, and it sets the variable parameter awHnd1l 
to the window’s auxiliary window record. 


If the window has no auxiliary window record, GetAuxWin places the default window 
color table in awHnd1 and returns a value of FALSE. 
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For a description of the auxiliary window record, see “The Auxiliary Window Record” 
on page 4-73. 


Low-Level Routines 


This section describes the low-level routines that are called by higher-level Window 
Manager routines. Ordinarily, you won’t need to use these routines. 


CheckUpdate 


DESCRIPTION 


ClipAbove 


DESCRIPTION 
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The Event Manager uses the CheckUpdate function to scan the window list for 
windows that need updating. 


FUNCTION CheckUpdate (VAR theEvent: EventRecord): Boolean; 





theEvent Anevent record to be filled in if a window needs updating. 


The CheckUpdate function scans the window list from front to back, checking for a 
visible window that needs updating (that is, a visible window whose update region is 
not empty). If it finds one whose window record contains a picture handle, it redraws 
the window itself and continues through the list. If it finds a window record whose 
update region is not empty and whose window record does not contain a picture handle, 
it stores an update event in the parameter theEvent and returns TRUE. If it finds no 
such window, it returns FALSE. 











The Event Manager is the only software that ordinarily calls CheckUpdate. 


The Window Manager uses the ClipAbove procedure to determine the clip region of 
the Window Manager port for displaying a window. 














PROCEDURE ClipAbove (window: WindowPeek) ; 


window A pointer to the window’s complete window record. 


The ClipAbove procedure sets the clip region of the Window Manager port to 
be the area of the desktop that intersects the current clip region, minus the 
structure regions of all the windows in front of the specified window. 
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DrawNew 


DESCRIPTION 
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The ClipAbove procedure retrieves the desktop region from the global 
variable GrayRgn. 


The Window Manager uses the SaveO1d procedure to save a window’s current 
structure and content regions preparatory to updating the window. 


PROCEDURE SaveOld (window: WindowPeek) ; 





window A pointer to the window’s complete window record. 


The SaveOld procedure saves the specified window’s current structure region and 
content region for the DrawNew procedure. Each call to SaveOld must be balanced 
by a subsequent call to DrawNew. 


The Window Manager uses the DrawNew procedure to erase and update changed 
window regions. 














PROCEDURE DrawNew (window: WindowPeek; update: Boolean); 





window A pointer to the window’s complete window record. 


update A Boolean value that determines whether the regions are updated. 


The DrawNew procedure erases the parts of a window’s structure and content regions 


that are part of the window’s former state and part of its new state but not both. That is, 


(OldStructure XOR NewStructure) UNION (OldContent XOR NewContent) 





If the update parameter is set to TRUE, DrawNew also updates the erased regions. 


WARNING 
In Pascal, SaveOld and DrawNew are not nestable. a 


ASSEMBLY-LANGUAGE INFORMATION 


In assembly language, you can nest SaveOld and DrawNew if you save and restore the 


values of the global variables OldStructure and OldContent. 
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PaintOne 


DESCRIPTION 
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The Window Manager uses the PaintOne procedure to redraw the invalid, exposed 
portions of one window on the desktop. 


PROCEDURE PaintOne (window: WindowPeek; clobberedRgn: RgnHandle); 


window A pointer to the window’s complete window record. 


clobberedRgn 
A handle to the region that has become invalid. 


The PaintOne procedure “paints” the invalid portion of the specified window and 
all windows above it. It draws as much of the window frame as is in clobberedRgn 
and, if some content region is exposed, erases the exposed area (paints it with the 
background pattern) and adds it to the window’s update region. If the value of the 
window parameter is NIL, the window is the desktop, and PaintOne paints it with 
the desktop pattern. 


ASSEMBLY-LANGUAGE INFORMATION 


The global variables SaveUpdate and PaintWhite are flags used by PaintOne. 
Normally both flags are set. Clearing SaveUpdate prevents clobberedRgn from being 
added to the window’s update region. Clearing PaintWhite prevents clobberedRgn 
from being erased before being added to the update region (this is useful, for example, if 
the background pattern of the window isn’t the background pattern of the desktop). The 
Window Manager sets both flags periodically, so you should clear the appropriate flags 
each time you need them to be clear. 
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The Window Manager uses the Paint Behind procedure to redraw a series of windows 
in the window list. 


PROCEDURE PaintBehind (startWindow: WindowPeek; 
clobberedRgn: RgnHandle) ; 








startWindow 
A pointer to the window’s complete window record. 


clobberedRgn 
A handle to the region that has become invalid. 
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The PaintBehind procedure calls PaintOne for startWindow and all the windows 
behind st artWindow, clipped to clobberedRgn. 
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CalcVis 


DESCRIPTION 





Because PaintBehind clears the global variable PaintWhite before calling 
PaintOne, clobberedRgn isn’t erased. The PaintWhite global variable is reset 
after the call to PaintOne. 


The Window Manager uses the CalcVis procedure to calculate the visible region 
of a window. 





PROCEDURE CalcVis (window: WindowPeek) ; 











window A pointer to the window’s complete window record. 


The CalcVis procedure calculates the visible region of the specified window by starting 
with its content region and subtracting the structure region of each window in front of it. 


CalcVisBehind 


DESCRIPTION 


The Window Manager uses the CalcVisBehind procedure to calculate the visible 
regions of a series of windows. 


PROCEDURE CalcVisBehind (startWindow: WindowPeek; 
clobberedRgn: RgnHandle) ; 





startWindow 
A pointer to a window’s window record. 


clobberedRgn 
A handle to the desktop region that has become invalid. 





The CalcVisBehind procedure calculates the visible regions of the window specified 
by the startWindow parameter and all windows behind startWindow that intersect 
clobberedRgn. It is called after PaintBehind. 
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Application-Defined Routine 


This section describes the window definition function. The Window Manager supplies 
window definition functions that handle the standard window types described in “Types 
of Windows” beginning on page 4-8. 


The Window Definition Function 


If your application defines its own window types, you must supply your own window 
definition function to handle them. Store your definition function as a resource of type 
'WDEF ' with an ID from 128 through 4096. (Window definition function resource IDs 0 
and 1 are the default window definition functions; resource IDs 2 through 127 are 
reserved by Apple Computer, Inc.) 


Your window definition function can support up to 16 variation codes, which are 
identified by integers 0 through 15. To invoke your own window type, you specify the 
window’s definition ID, which contains the resource ID of the window’s definition 
function in the upper 12 bits and the variation code in the lower 4 bits. Thus, for a given 
resource ID and variation code, the window definition ID is 


(16 * resource ID) + (variation code) 


When you create a window, the Window Manager calls the Resource Manager to access 
the window definition function. The Resource Manager reads the window definition 
function into memory and returns a handle to it. The Window Manager stores this 
handle in the windowDefProc field of the window record. (If 24-bit addressing is in 
effect, the Window Manager stores the variation code in the lower 4 bits of the 
windowDefProc field; if 32-bit addressing is in effect, the Window Manager stores the 
variation code elsewhere.) Later, when it needs to perform a type-dependent action on 
the window, the Window Manager calls the window definition function and passes it the 
variation code as a parameter. 


MyWindow 
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The window definition function is responsible for drawing the window frame, reporting 
the region where mouse-down events occur, calculating the window’s structure region 
and content region, drawing the size box, resizing the window frame when the user 
drags the size box, and performing any customized initialization or disposal tasks. 


You can give your window definition function any name you wish. It takes four 


parameters and returns a result code: 


FUNCTION MyWindow (varCode: Integer; theWindow: WindowPtr; 
message: Integer; param: LongInt): LongInt; 








varCode The window’s variation code. 


theWindow A pointer to the window’s window record. 
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message A code for the task to be performed. The message parameter has one of 
these values: 


CONST 
wDraw = 0; {draw window frame} 
wHit = 1; {report where mouse-down event } 
{ occurred} 
wCalcRgns = 2; {calculate strucRgn and contRgn} 
wNew = 3; {perform additional } 
{ initialization} 
wDispose = 4; {perform additional disposal } 
{ tasks} 
wGrow = 5; {draw grow image during resizing} 
wDrawGIcon = 6; {draw size box and scroll bar } 


{ outline} 


The subsections that follow explain each of these tasks in detail. 


param Data associated with the task specified by the message parameter. If the 
task requires no data, this parameter is ignored. 


Your window definition function performs whatever task is specified by the message 
parameter and returns a function result if appropriate. If the task performed requires no 
result code, return 0. 


The function’s entry point must be at the beginning of the function. 


You can set up the various tasks as subroutines inside the window definition function, 
but you’re not required to do so. 


Drawing the Window Frame 


When you receive a wDraw message, draw the window frame in the current graphics 
port, which is the Window Manager port. 


You must make certain checks to determine exactly how to draw the frame. If the value 
of the visible field in the window record is FALSE, you should do nothing; otherwise, 
you should examine the param parameter and the status flags in the window record: 


m If the value of param is 0, draw the entire window frame. 


m If the value of param is 0 and the hilited field in the window record is TRUE, 
highlight the frame to show that the window is active. 





If the value of the goAwayF1agq field in the window record is also TRUE, draw a 
close box in the window frame. 





If the value of the spareFlag field in the window record is also TRUE, draw a 
zoom box in the window frame. 


m If the value of the param parameter is wInGoAway, add highlighting to, or remove 
it from, the window’s close box. Figure 4-19 on page 4-46 illustrates the close box 
with and without highlighting as drawn by the Window Manager’s window 
definition function. 
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mw If the value of the param parameter is wInZoom, add highlighting to, or remove it 
from, the window’s zoom box. Figure 4-20 on page 4-47 illustrates the zoom box 
with and without highlighting as drawn by the Window Manager’s window 
definition function. 


Note 

When the Window Manager calls a window definition function 
with a message of wDraw, it stores a value of type Integer in the 
param parameter without clearing the high-order word. When 
processing the wDraw message, use only the low-order word of the 
param parameter. 


The window frame typically but not necessarily includes the window’s title, which 
should be displayed in the system font and system font size. The Window Manager 
port is already set to use the system font and system font size. 


When designing a title bar that includes the window title, allow at least 16 pixels 
vertically to support localization for script systems in which the system font can be no 
smaller than 12 points. 


Note 
Nothing drawn outside the window’s structure region is visible. 


Returning the Region of a Mouse-Down Event 


When you receive a wHit message, you must determine where the cursor was when the 
mouse button was pressed. The wHit message is accompanied by the mouse location, in 
global coordinates, in the param parameter. The vertical coordinate is in the high-order 
word of the parameter, and the horizontal coordinate is in the low-order word. You 
return one of these constants: 


CONST 

wNoHit = 0; {none of the following} 

wiInContent = 1; {in content region (except grow, if active) } 

winDrag = 2; {in drag region} 

winGrow = 3; {in grow region (active window only) } 

wiInGoAway = 4; {in go-away region (active window only) } 

wiInZoomIn = 5; {in zoom box for zooming in (active window } 
{ only) } 

wiInZoomOut = 6; {in zoom box for zooming out (active window } 
{ only) } 


The return value wNoHit might mean (but not necessarily) that the point isn’t in the 
window. The standard window definition functions, for example, return wNoHit if the 
point is in the window frame but not in the title bar. 


Return the constants wInGrow, wInGoAway, wInZoomIn, and wInZoomOut only if the 
window is active—by convention, the size box, close box, and zoom box aren’t drawn if 
the window is inactive. In an inactive document window, for example, a mouse-down 
event in the part of the title bar that would contain the close box if the window were 
active is reported as wInDrag. 
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Calculating Regions 


When you receive the wCalcRgns message, you calculate the window’s structure and 
content regions based on the current graphics port’s port rectangle. These regions, whose 
handles are in the strucRgn and contRgn fields of the window record, are in global 
coordinates. The Window Manager requests this operation only if the window is visible. 


WARNING 

When you calculate regions for your own type of window, do not alter 
the clip region or the visible region of the window’s graphics port. The 
Window Manager and QuickDraw take care of this for you. Altering the 
clip region or visible region may damage other windows. & 


Initializing a New Window 


When you receive the wNew message, you can perform any type-specific initialization 
that may be required. If the content region has an unusual shape, for example, you might 
allocate memory for the region and store the region handle in the dat aHand_1e field of 
the window record. The initialization routine for a standard document window creates 
the wStateData record for storing zooming data. 


Disposing of a Window 


When you receive the wDispose message, you can perform any additional tasks 
necessary for disposing of a window. You might, for example, release memory that was 
allocated by the initialization routine. The dispose routine for a standard document 
window disposes of the wStateData record. 


Resizing a Window 


When you receive the wGrow message, draw a grow image of the window. With the 
wGrow message you receive a pointer to a rectangle, in global coordinates, whose 
upper-left corner is aligned with the port rectangle of the window’s graphics port. Your 
grow image should fit inside the rectangle. As the user drags the mouse, the Window 
Manager sends repeated wGrow messages, so that you can change your grow image to 
match the changing mouse location. 


Draw the grow image in the current graphics port, which is the Window Manager port, 
in the current pen pattern and pen mode. These are set up (as gray and not Pat Xor) to 
conform to the Macintosh user interface guidelines. 


The grow routine for a standard document window draws a dotted (gray) outline of the 
window and also the lines delimiting the title bar, size box, and scroll bar areas. 


Drawing the Size Box 


When you receive the wDrawGIcon message, you draw the size box in the content 
region if the window is active—if the window is inactive, draw whatever is appropriate 
to show that the window cannot currently be sized. 
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Note 

If the size box is located in the window frame instead of the content 
region, do nothing in response to the wWorawGIcon message, instead 
drawing the size box in response to the wDraw message. @ 


The routine that draws a size box for an active document window draws the size box in 
the lower-right corner of the port rectangle of the window’s graphics port. It also draws 
lines delimiting the size box and scroll bar areas. For an inactive document window, it 
erases the size box and draws the delimiting lines. 


Resources 


This section describes the resources used by the Window Manager: 


m the 'WIND' resource, used for describing the characteristics of windows 





m the 'WDEF' resource, which holds a window definition function 


m the 'wctb' resource, which defines the colors to be used for a window’s frame 
and highlighting 


The Window Resource 


You typically define a window resource for each type of window that your application 
creates. Figure 4-24 illustrates a compiled 'WIND' resource. 


Figure 4-24 Structure of a compiled window ('WIND") resource 


Positioning specication 
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A compiled version of a window resource contains the vollowing elements: 


m The upper-left and lower-right corners, in global coordinates, of a rectangle 
that defines the initial size and placement of the window’s content region. 
Your application can change this rectangle before displaying the window, 
either programmatically or through an optional positioning code described 
later in this section. 


m The window’s definition ID, which incorporates both the resource ID of the window 
definition function that will handle the window and an optional variation code. 
Together, the window definition function resource ID and the variation code define a 
window type. Place the resource ID of the window definition function in the upper 
12 bits of the definition ID. Window definition functions with IDs 0 through 127 are 
reserved for use by Apple Computer, Inc. Place the optional variation code in the 
lower 4 bits of the definition ID. 


If you’re using one of the standard window types (described in “Types of Windows” 
beginning on page 4-8), the definition ID is one of the window-type constants: 


CONST 
documentProc = 0; {movable, sizable window, } 
{ no zoom box} 
daBoxProc = 1; {alert box or modal dialog box} 
plainDBox = 2; {plain box} 
altDBoxProc = 3; {plain box with shadow} 
noGrowDocProc = 4; {movable window, no size box or } 
{ zoom box} 
movableDBoxProc = 9; {movable modal dialog box} 
zoomDocProc = 8; {standard document window} 
zoomNoGrow = 12; {zoomable, nonresizable window} 
rDocProc = 16; {rounded-corner window} 


You can also add a zoom box to a movable modal dialog box by specifying the sum 
of two constants: movableDBoxProc + zoomDocProc, but a zoom box is not 
recommended on any dialog box. 


You can control the angle of curvature on a rounded-corner window (window type 
rDocP roc) by adding one of these integers: 


Diameters of 


Window definition ID curvature 
rDocProc 16, 16 
rDocProc + 2 4,4 
rDocProc + 4 6,6 
rDocProc + 6 10, 10 


a A specification that determines whether the window is visible or invisible. This 
characteristic controls only whether the Window Manager displays the window, not 
necessarily whether the window can be seen on the screen. (A visible window entirely 
covered by other windows, for example, is “visible” even though the user cannot see 
it.) You typically create a new window in an invisible state, build the content area of 
the window, and then display the completed window. 
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m A specification that determines whether or not the window has a close box. The 
Window Manager draws the close box when it draws the window frame. The window 
type specified in the second field determines whether a window can support a close 
box; this field determines whether the close box is present. 


m A reference constant, which your application can use for whatever data it needs to 
store. When it builds a new window record, the Window Manager stores, in the 
refCon field, whatever value you specify in the fifth element of the window resource. 
You can also put a placeholder here and then set the refCon field yourself with the 
SetWRefCon procedure. 


m A string that specifies the window title. The first byte of the string specifies the length 
of the string (that is, the number of characters in the title plus 1 byte for the length), 
in bytes. 


ms Anoptional positioning specification that overrides the window position established 
by the rectangle in the first field. The positioning value can be one of the integers 
defined by the constants listed here. In these constant names, the terms have the 
following meanings: 


center Centered both horizontally and vertically, relative either to a 
screen or to another window (if a window to be centered 
relative to another window is wider than the window that 
preceded it, it is pinned to the left edge; a narrower window 
is centered) 


stagger Located 10 pixels to the right and 10 pixels below the 
upper-left corner of the last window (in the case of staggering 
relative to a screen, the first window is placed just below 
the menu bar at the left edge of the screen, and subsequent 
windows are placed on that screen relative to the 
first window) 


alert position Centered horizontally and placed in the “alert position” 
vertically, that is, with about one-fifth of the window or 
screen above the new window and the rest below 


parent window The window in which the user was last working 


The seventh element of the resource can contain one of the values specified by 
these constants: 


CONST noAutoCenter 


0x0000; {use initial } 
{ location} 


centerMainScreen Ox280A; {center on main } 
{ screen} 
Ox300A; {place in alert } 


{ position on main } 


alertPositionMainScreen 


{ screen} 


staggerMainScreen Ox380A; {stagger on main } 


{ screen} 


centerParentWindow OxA80A; {center on parent } 


{ window} 
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alertPositionParentWindow OxBOOA; {place in alert } 

{ position on } 

{ parent window} 
staggerParentWindow = O0xB80A; {stagger relative } 


{ to parent window} 


centerParentWindowScreen Ox680A; {center on parent } 
{ window screen} 
alertPositionParentWindowScreen 
= 0x700A; {place in alert } 
{ position on } 
{ parent window } 
{ screen} 
staggerParentWindowScreen = 0x780A; {stagger on parent } 


{ window screen} 


The positioning constants are convenient when the user is creating new documents or 
when you are handling your own dialog boxes and alert boxes. When you are creating 
anew window to display a previously saved document, however, you should display 
the new window in the same rectangle as the previous window (that is, the window 
the document occupied when it was last saved). For more information, see 
“Positioning a Document Window on the Desktop” beginning on page 4-30. 


Use the Get NewCWindow or Get NewWindow function to read a 'WIND' resource. Both 
functions create a new window record and fill it in according to the values specified in a 
"WIND" resource. 


The Window Definition Function Resource 


Window definition functions are stored as resources of type 'WDEF'. The 'WDEF' 
resource is simply the executable code for the window definition function. 





The two standard window definition functions supplied by the Window Manager use 
resource IDs 0 and 1. 


The Window Color Table Resource 


You can specify your own window color tables as resources of type 'wctb'. 


Ordinarily, you should not define your own window color tables, unless you have some 
extraordinary need to control the color of a window’s frame or text highlighting. To 
assign a table to a window when you create the window, provide a window color table 
('wctb") resource with the same resource ID as the 'WIND' resource from which you 
create the window. 


The window color table resource is an exact image of the window color table data 
structure. Figure 4-25 illustrates the contents of a compiled 'wctb' resource. 
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Figure 4-25 Structure of a compiled window color table ('wctb") resource 
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A compiled version of a window resource contains the following elements: 
m Anunused field 6 bytes long. 


m An integer that specifies the number of entries in the resource (that is, the number of 
color specification records) minus 1. 


m Aseries of color specification records, each of which consists of a 2-byte part identifier 
and three 2-byte color values. The part identifier is an integer specified by one of 
these constants: 





CONST wContentColor = 0; {content region background} 

wFrameColor = 1; {window frame} 

wlextColor = 2; {window title and button text} 

wHiliteColor = 3; {reserved} 

wlitleBarColor = 4; {reserved} 

wHiliteColorLight = 5; {lightest stripes in title bar } 
{ and lightest dimmed text} 

wHiliteColorDark = 6; {darkest stripes in title bar } 
{ and darkest dimmed text} 

wlitleBarLight = 7; {lightest parts of title bar } 





{ background} 
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wlitleBarDark = 8; {darkest parts of title bar } 
{ background} 

wDialogLight = 9; {lightest element of dialog box } 
{ frame} 

wDialogDark = 10; {darkest element of dialog box } 
{ frame} 

wlingeLight = 11; {lightest window tinging} 

wlingeDark = 12; {darkest window tinging} 


The color values are simply the intensity of the red, green, and blue in each window 
part (see Inside Macintosh: Imaging for a description of RGB color). 
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Summary of the Window Manager 


Pascal Summary 


Constants 


CONST 
{window types} 





documentProc = 0; {movable, sizable window, no zoom box} 
daBoxProc = 1; {alert box or modal dialog box} 
plainDBox = 2; {plain box} 
altDBoxProc = 3; {plain box with shadow} 
noGrowDocProc = 4; {movable window, no size box or } 

{ zoom box} 
movableDBoxProc =D; {movable modal dialog box} 
zoomDocProc = 8; {standard document window} 
zoomNoGrow = 12; {zoomable, nonresizable window} 
rDocProc = 16; {rounded-corner window} 


{window kinds} 
dialogKind = 2; {dialog or alert box window} 
userKind = 8; {window created by the application} 


{part codes returned by FindWindow} 





inDesk = 0; {none of the following} 

inMenuBar = 1; {in menu bar} 

inSysWindow = 2% {in desk accessory window} 

inContent = 3; {anywhere in content region except size } 
{ box if window is active, } 
{ anywhere including size box if window } 
{ is inactive} 

inDrag = 4; {in drag (title bar) region} 

inGrow = 5; {in size box (active window only) } 

inGoAway = 6; {in close box} 

inZoomIn = obs {in zoom box (window in standard state) } 

inZoomOut = 8; {in zoom box (window in user state) } 


{axis constraints on DragGrayRgn} 


noConstraint = 0; {no constraints} 
hAxisOnly = {move on horizontal axis only} 
vAxisOnly = 2; {move on vertical axis only} 
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{window definition function task codes} 





wDraw = 0; {draw window frame} 

wHit = 1; {report where mouse-down occurred} 
wCalcRgns = 2; {calculate strucRgn and contRgn} 

wNew = 3; {perform additional initialization} 
wDispose = 4; {perform additional disposal tasks} 
wGrow = 5; {draw grow image during resizing} 
wDrawGIcon = 6; {draw size box and scroll bar outline} 


{window definition function wHit return codes} 


wNoHit = 0; {none of the following} 


wiInContent 1; {anywhere in content region except size } 
{ box if window is active, } 
{ anywhere including size box if window } 


{ is inactive} 


wiInDrag = 2; {in drag (title bar) region} 

winGrow = 135 {in size box (active window only) } 
wiInGoAway = 4; {in close box} 

wiInZoomiIn = 5; {in zoom box (window in standard state) } 
wiInZoomOut = 6; {in zoom box (window in user state) } 


{window color information table part codes} 





wContentColor = 0; {content region background} 
wFrameColor = 1; {window outline} 

wTextColor = 25 {window title and button text} 
wHiliteColor = 3; {reserved} 

wlitleBarColor = 4; {reserved} 

wHiliteColorLight = 5; {lightest stripes in title bar } 

{ and lightest dimmed text} 
wHiliteColorDark = 6; {darkest stripes in title bar } 

{ and darkest dimmed text} 
wlitleBarLight = 7; {lightest parts of title bar background} 
wlitleBarDark = 8; {darkest parts of title bar background} 
wDialogLight = 9; {lightest element of dialog box frame} 
wDialogDark = 10; {darkest element of dialog box frame} 
wlingeLight = 11; {lightest window tinging} 
wlingeDark = 12; {darkest window tinging} 


{resource ID of desktop pattern} 
deskPatID = 16; 
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Data Types 
TYPE CWindowPtr = CGrafPtr; 
CWindowPeek = *“CWindowRecord; 
CWindowRecord = 
RECORD 
port: CGrafPort; {window's graphics port} 
windowKind: Integer; {class of window} 
visible: Boolean; {visibility} 
hilited: Boolean; {highlighting} 
goAwayFlag: Boolean; {presence of close box} 
spareFlag: Boolean; {presence of zoom box} 
strucRgn: RgnHandle; {handle to structure region} 
contRgn: RgnHandle; {handle to content region} 
updateRgn: RgnHandle; {handle to update region} 
windowDefProc: Handle; {handle to window definition function} 
dataHandle: Handle; {handle to window state data record} 
titleHandle: StringHandle; {handle to window title} 
titleWidth: Integer; {title width in pixels} 
controlList: ControlHandle; {handle to control list} 
nextWindow: CWindowPeek; {pointer to next window record in } 
{ window list} 
windowPic: PicHandle; {handle to optional picture} 
refCon: LongInt; {storage available to your application} 
END; 
WindowPtr = GrafPtr; 
WindowPeek = “WindowRecord; 
WindowRecord = 
RECORD {all fields have same use as } 
{ in color window record} 
port: GrafPort; {window's graphics port} 
windowKind: Integer; {class of window} 
visible: Boolean; {visibility} 
hilited: Boolean; {highlighting} 
goAwayFlag: Boolean; {presence of close box} 
spareFlag: Boolean; {presence of zoom box} 
strucRgn: RgnHandle; {handle to structure region} 
contRgn: RgnHandle; {handle to content region} 
updateRgn: RgnHandle; {handle to update region} 
windowDefProc: Handle; {handle to window definition function} 
dataHandle: Handle; {handle to window state data record} 
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{handle to window title} 

{title width in pixels} 

{handle to control list} 

{pointer to next window record in } 

{ window list} 

{handle to optional picture} 

{storage available to your application} 


{zoom state data record} 


{size and location established by user} 
{size and location established by application} 


titleHandle: StringHandle; 
titleWidth: Integer; 
controlList: ControlHandle; 
nextWindow: WindowPeek; 
windowPic: PicHandle; 
refCon: LongInt; 
END; 
WStateDataPtr = *WStateData; 
WStateDataHandle = *“WStateDataPtr; 
WStateData = 
RECORD 
userState: Rect; 
stdState: Rect; 
END; 


WCTabPtr = “WinCTab; 


WCTabHandle = 


WinCTab = 
RECORD 
wCSeed: 
wCReserved: 
ctSize: 
ctTable: 


END; 


ColorSpec = 
RECORD 
value: 
rgb: 
END; 


AuxWinHandle 
AuxWinPtr = 


AuxWinRec 

RECORD 
awNext: 
awOwner: 
awCTable: 


dialogCItem: 


“WCTabPtr; 


LongInt; 
Integer; 
Integer; 
ARRAY [0. 


Integer; 
RGBColor; 


“AuxWinPtr; 


“AuxWinRec; 


AuxWinHandle; 
WindowPtr; 
CTabHandle; 
Handle; 


{window color information table} 


{reserved} 
{reserved} 


{number of entries in table -1} 


-4] OF ColorSpec; 


{array of color specification records} 


{part identifier} 
{RGB value} 


{auxiliary window record} 


{handle to next record} 

{pointer to window} 

{handle to color table} 

{storage used by Dialog Manager} 
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awFlags: LongInt; {reserved} 
awReserved: CTabHandle; {reserved} 
awRefCon: LongInt; {reference constant, for } 


{ use by application} 


END; 


Window Manager Routines 


Initializing the Window Manager 














PROCEDURE InitWindows; 


Creating Windows 


FUNCTION GetNewCWindow (windowID: Integer; wStorage: Ptr; 
behind: WindowPtr): WindowPtr; 


FUNCTION GetNewWindow (windowID: Integer; wStorage: Ptr; 
behind: WindowPtr): WindowPtr; 


FUNCTION NewCWindow (wStorage: Ptr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
procID: Integer; behind: WindowPtr; 


goAwayFlag: 





Boolean; 


refCon: LongInt): WindowPtr; 


FUNCTION NewWindow (wStorage: Ptr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
theProc: Integer; behind: WindowPtr; 


goAwayFlag: 


Boolean; 


refCon: LongInt): WindowPtr; 


Naming Windows 





























PROCEDURE SetWTitle (theWindow: 
PROCEDURE GetWTitle (theWindow: 
Displaying Windows 

PROCEDURE DrawGrowIcon (theWindow: 
PROCEDURE SelectWindow (theWindow: 
PROCEDURE ShowWindow (theWindow: 
PROCEDURE HideWindow (theWindow: 
PROCEDURE ShowHide (theWindow: 
PROCEDURE HiliteWindow (theWindow: 
PROCEDURE BringToFront (theWindow: 
PROCEDURE SendBehind (theWindow, 
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WindowPtr; title: Str255); 
WindowPtr; VAR title: Str255); 


WindowPtr) ; 

WindowPtr) ; 

WindowPtr) ; 

WindowPtr) ; 

WindowPtr; showFlag: Boolean); 
WindowPtr; fHilite: Boolean); 
WindowPtr) ; 

behindWindow: WindowPtr); 
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Retrieving Window Information 


























FUNCTION FindWindow (thePoint: Point; 
VAR theWindow: WindowPtr): Integer; 
FUNCTION FrontWindow WindowPtr; 
Moving Windows 
PROCEDURE DragWindow (theWindow: WindowPtr; 
startPt: Point; boundsRect: Rect); 
PROCEDURE MoveWindow (theWindow: WindowPtr; 
hGlobal, vGlobal: Integer; front: Boolean); 
FUNCTION DragGrayRgn (theRgn: RgnHandle; startPt: Point; 
limitRect, slopRect: Rect; axis: Integer; 
actionProc: ProcPtr): LongInt; 
FUNCTION PinRect (theRect: Rect; thePt: Point): LongInt; 
Resizing Windows 
FUNCTION GrowWindow (theWindow: WindowPtr; 
startPt: Point; sizeRect: Rect): LongInt; 
PROCEDURE SizeWindow (theWindow: WindowPtr; w, h: Integer; 
fUpdate: Boolean) ; 
Zooming Windows 
FUNCTION TrackBox (theWindow: WindowPtr; thePt: Point; 
partCode: Integer): Boolean; 
PROCEDURE ZoomWindow (theWindow: WindowPtr; 
partCode: Integer; front: Boolean); 
Closing and Deallocating Windows 
FUNCTION TrackGoAway (theWindow: WindowPtr; thePt: Point): Boolean; 
PROCEDURE CloseWindow (theWindow: WindowPtr) ; 
PROCEDURE DisposeWindow (theWindow: WindowPtr) ; 
Maintaining the Update Region 
PROCEDURE BeginUpdate (theWindow: WindowPtr) ; 
PROCEDURE EndUpdate (theWindow: WindowPtr); 
PROCEDURE InvalRect (badRect: Rect); 
PROCEDURE InvalRgn (badRgn: RgnHandle) ; 
PROCEDURE ValidRect (goodRect: Rect); 
PROCEDURE ValidRgn (goodRgn: RgnHandle) ; 
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Setting and Retrieving Other Window Characteristics 


PROCEDURE SetWindowPic 
FUNCTION GetWindowPic 





PROCEDURE SetWRefCon 











FUNCTION GetWRefCon 
FUNCTION GetWVariant 


Manipulating the Desktop 


PROCEDURE SetDeskCPat 





5 


FUNCTION GetGrayRgn 
PROCEDURE GetCWMgrPort 
PROCEDURE GetWMgrPort 





£5 


(theWindow: 
(theWindow: 
(theWindow: 
(theWindow: 
(theWindow: 


(deskPixPat: 
RgnHandle; 
(VAR wMgrCPort: 


(VAR wPort: 


Manipulating Window Color Information 


PROCEDURE SetWinColor 





FUNCTION GetAuxWin 


Low-Level Routines 
FUNCTION CheckUpdate 
PROCEDURE ClipAbove 
PROCEDURE SaveOld 





E 


PROCEDURE DrawNew 
PROCEDURE PaintOne 





PROCEDURE PaintBehind 














PROCEDURE CalcVis 
PROCEDURE CalcVisBehind 





Application-Defined Routine 


The Window Definition Function 


FUNCTION MyWindow 
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(theWindow: 


newColorTable: 


(theWindow: 


VAR awHndl: 


(VAR theEvent: 


(window: 
(window: 
(window: 


(window: 


(startWindow: 
clobberedRgn: 


WindowPeek; 


WindowPeek; 


WindowPtr; 


WindowPtr): 


WindowPtr; 


WindowPtr): 
WindowPtr): 


Pic: PicHandle) ; 
PicHandle; 
data: LongInt); 
LongInt; 


Integer; 


PixPatHandle); 


GrafPtr); 


WindowPtr; 


WindowPtr; 


AuxWinHandle) : 


WindowPeek) ; 


WindowPeek) ; 


(window: WindowPeek) ; 


(startWindow: 
clobberedRgn: 


(varCode: 


EventRecord) : 


update: 
clobberedRgn: 





message: 


Integer; 
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Integer; 


CGrafPtr); 


WCTabHandle); 


Boolean; 


Boolean; 


Boolean) ; 


RgnHandle) ; 


WindowPeek; 
RgnHandle) ; 


WindowPeek; 
RgnHandle) ; 


theWindow: WindowPtr; 
param: LongInt): 


LongInt; 
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C Summary 


Constants 


enum { 


hi 


/*window types*/ 
documentProc = 


x 


dBoxProc = 


x 


plainDBox = 
altDBoxProc = 


noGrowDocProc = 


. 


x 


movableDBoxProc = 


x 


zoomDocProc = 


x 


zoomNoGrow = 


Fo oOo FF WN FO 
~ 


oO. 


rDocProc = 


/*window kinds*/ 
dialogKind = 2, 
userKind = 8, 


/*movable, 


sizable window, no zoom box*/ 


/*alert box or modal dialog box*/ 
/*plain box*/ 
/*plain box with shadow*/ 


/*movable window, 


no size box or zoom box*/ 


/*movable modal dialog box*/ 


/*standard document window*/ 


/*zoomable, 


nonresizable window*/ 


/*rounded-corner window*/ 


/*dialog or alert box window*/ 


/*window created by the application*/ 


/*part codes returned by FindWindow*/ 


inDesk = 0, 


inMenuBar = 1, 


1 
inSysWindow = 2, 
inContent = 3 


v 


inDrag = 


x 


inGrow = 


x 


inGoAway = 


inZoomIn = 


x 


@oanrzA on oO ss 
x 


inZoomOut = 


enum { 


hi 


/*none of the following*/ 


/*in menu bar*/ 


/*in desk accessory window*/ 





/*anywhere in content region except size box if*/ 


/* window is active, 


/* size box if window 


/*in 
/*in 
/*in 
/*in 


/*in 


drag (title bar) 
size box (active 
close box*/ 

zoom box (window 


zoom box (window 


/*axis constraints on DragGrayRgn*/ 


noConstraint = 0, 
hAxisOnly = 1, 
vAxisOnly = 2 


/*no 


constraints*/ 


anywhere including */ 


is inactive*/ 
region*/ 


window only) */ 


in standard state) */ 
in user state) */ 


/*move on horizontal axis only*/ 


/*move on vertical axis only*/ 
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enum { 


/*window definition function task codes*/ 





wDraw = 0, /*draw window frame*/ 

wHit = 1, /*report where mouse-down occurred*/ 
wCalcRgns = 2, /*calculate strucRgn and contRgn*/ 

wNew = 3, /*perform additional initialization*/ 
wDispose = 4, /*perform additional disposal tasks*/ 
wGrow = 5, /*draw grow image during resizing*/ 
wDrawGIcon = 6, /*draw size box and scroll bar outline*/ 


/*window definition function wHit return codes*/ 


wNoHit = 0, /*none of the following*/ 

wiInContent = 1, /*in content region (except grow, if active) */ 

wiInDrag = 2, /*in drag region*/ 

wilnGrow = 3, /*in grow region (active window only) */ 

wiInGoAway = 4, /*in go-away region (active window only) */ 

winZoomiIn = Dy /*in zoom box for zooming in (active window */ 
/* only) */ 

winZoomOut = 6, /*in zoom box for zooming out (active window */ 
/* only) */ 

deskPatID = 16, /*resource ID of desktop pattern*/ 


/*window color information table part codes*/ 
wContentColor = 0, /*the background of the window's */ 
/* content region*/ 


wFrameColor = 1, /*the window outline*/ 

wTextColor = 2, /*window title and text in buttons*/ 
wHiliteColor =73, /*reserved*/ 

wTitleBarColor = 4, /*reserved*/ 

wHiliteColorLight = 5, /*lightest stripes in title bar */ 

/* and lightest dimmed text*/ 
wHiliteColorDark = 6, /*darkest stripes in title bar */ 

/* and darkest dimmed text*/ 
wlitleBarLight = 7, /*lightest parts of title bar background*/ 
wlitleBarDark = 8, /*darkest parts of title bar background*/ 
wDialogLight = 9, /*lightest element of dialog box frame*/ 
wDialogDark = 10, /*darkest element of dialog box frame*/ 
wlingeLight = 11, /*lightest window tinging*/ 
wTingeDark = 12 /*darkest window tinging*/ 


}; 
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Data Types 


struct CWindowRecord { 


}; 


CGrafPort port; 

short windowKind; 
Boolean visible; 
Boolean hilited; 
Boolean goAwayFlag; 
Boolean spareFlag; 
RgnHandle strucRgn; 
RgnHandle contRgn; 
RgnHandle updateRgn; 
Handle windowDefProc; 
Handle dataHandle; 
StringHandle titleHandle; 
short titleWidth; 
ControlHandle controlList; 
struct CWindowRecord *nextWindow; 
PicHandle windowPic; 
long refCon; 


/*window's graphics port*/ 
/*class of the window*/ 
/*visibility*/ 

/*highlighting*/ 

/*presence of close box*/ 
/*presence of zoom box*/ 
/*handle to structure region*/ 
/*handle to content region*/ 
/*handle to update region*/ 
/*handle to window definition */ 
/* function*/ 

/*handle to window state data record*/ 
/*handle to window title*/ 
/*title width in pixels*/ 
/*handle to control list*/ 
/*next window in window list*/ 
/*handle to optional picture*/ 
/*storage available to your */ 
/* application*/ 


typedef struct CWindowRecord CWindowRecord; 


typedef CWindowRecord *CWindowPeek; 


struct WindowRecord { 





GrafPort port; 

short windowKind; 
Boolean visible; 
Boolean hilited; 
Boolean goAwayFlag; 
Boolean spareFlag; 
RgnHandle strucRgn; 
RgnHandle contRgn,; 
RgnHandle updateRgn; 
Handle windowDefProc; 
Handle dataHandle; 
StringHandle titleHandle; 
short titleWidth; 
ControlHandle controlList; 
struct WindowRecord *nextWindow; 
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/*window's graphics port*/ 

/*class of the window*/ 
/*visibility*/ 

/*highlighting*/ 

/*presence of close box*/ 
/*presence of zoom box*/ 

/*handle to structure region*/ 
/*handle to content region*/ 
/*handle to update region*/ 
/*handle to window definition */ 

/* function*/ 

/*handle to window state data record*/ 
/*handle to window title*/ 

/*title width in pixels*/ 

/*handle to window's control list*/ 


/*next window in window list*/ 
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PicHandle windowPic; /*handle to optional picture*/ 
long refCon; /*reference constant*/ 


}; 


typedef struct WindowRecord WindowRecord; 
typedef WindowRecord *WindowPeek; 


struct WStateData { 
Rect userState; /*user state*/ 
Rect stdState; /*standard state*/ 


hi 


typedef struct WStateData WStateData; 
typedef WStateData *WStateDataPtr, **WStateDataHandle; 


struct AuxWinRec { 


struct AuxWinRec **awNext; /*handle to next record*/ 

WindowPtr awOwner; /*pointer to window */ 

CTabHandle awCTable; /*handle to color table*/ 

Handle dialogCItem; /*storage used by Dialog Manager*/ 
long awF lags; /*reserved*/ 

CTabHandle awReserved; /*reserved*/ 

long awRefCon; /*reference constant, for use by */ 


/* application*/ 
}; 


typedef struct AuxWinRec AuxWinRec; 
typedef AuxWinRec *AuxWinPtr, **AuxWinHandle; 


struct WinCTab { 


long wCSeed; /*reserved*/ 

short wCReserved; /*reserved*/ 

short ctSize; /*number of entries in table —1*/ 
ColorSpec ctTable[5]; /*array of color specification records*/ 


}; 

typedef struct WinCTab WinCTab; 

typedef WinCTab *WCTabPtr, **WCTabHandle; 
Window Manager Routines 

Initializing the Window Manager 


pascal void InitWindows (void); 
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Creating Windows 


pascal WindowPtr GetNewCWindow 
(short windowID, void *wStorage, 
WindowPtr behind); 


pascal WindowPtr GetNewWindow 
(short windowID, void *wStorage, 
WindowPtr behind) ; 


pascal WindowPtr NewCWindow (void *wStorage, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible, 
short procID, WindowPtr behind, 
Boolean goAwayFlag, long refCon); 


pascal WindowPtr NewWindow (void *wStorage, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible, 
short theProc, WindowPtr behind, 
Boolean goAwayFlag, long refCon); 


Naming Windows 





pascal void SetWTitle (WindowPtr theWindow, ConstStr255Param title); 
pascal void GetWTitle (WindowPtr theWindow, Str255 title); 
Displaying Windows 

pascal void DrawGrowIcon (WindowPtr theWindow) ; 

pascal void SelectWindow (WindowPtr theWindow) ; 

pascal void ShowWindow (WindowPtr theWindow) ; 

pascal void HideWindow (WindowPtr theWindow) ; 

pascal void ShowHide (WindowPtr theWindow, Boolean showFlag) ; 
pascal void HiliteWindow (WindowPtr theWindow, Boolean fHilite); 

pascal void BringToFront (WindowPtr theWindow) ; 

pascal void SendBehind (WindowPtr theWindow, WindowPtr behindWindow) ; 


Retrieving Mouse Information 


pascal short FindWindow (Point thePoint, WindowPtr *theWindow) ; 


pascal WindowPtr FrontWindow (void) ; 


Moving Windows 


pascal void DragWindow (WindowPtr theWindow, Point startPt, 
const Rect *boundsRect) ; 


pascal void MoveWindow (WindowPtr theWindow, short hGlobal, 
short vGlobal, Boolean front); 
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pascal long DragGrayRgn 


pascal long PinRect 


Resizing Windows 


pascal long GrowWindow 


pascal void SizeWindow 


Zooming Windows 





pascal Boolean TrackBox 


pascal void ZoomWindow 


(RgnHandle theRgn, Point startPt, 
Rect *boundsRect, 
Rect *slopRect, 


const 
const 


short axis, 


(const Rect *theRect, Point *thePt); 


(WindowPtr theWindow, Point 


const Rect *bBox); 


startPt, 


(WindowPtr theWindow, 
Boolean fUpdate) ; 


short w, short h, 





(WindowPtr theWindow, Point 


short partCode) ; 


thePt, 


(WindowPtr theWindow, short 


Boolean front); 


partCode, 


Closing and Deallocating Windows 


pascal Boolean TrackGoAway 
pascal void CloseWindow 


pascal void DisposeWindow 


Maintaining the Update Region 


pascal void BeginUpdate 


pascal void EndUpdate 


pascal void InvalRect 


pascal void InvalRgn 
void ValidRect 


void ValidRgn 


pascal 


pascal 


(WindowPtr theWindow, Point thePt); 
(WindowPtr theWindow) ; 


(WindowPtr theWindow) ; 


(WindowPtr theWindow) ; 
(WindowPtr theWindow) ; 
(const Rect *badRect) ; 
(RgnHandle badRgn) ; 
(const Rect *goodRect) ; 
(RgnHandle goodRgn) ; 


Setting and Retrieving Other Window Characteristics 


pascal void SetWindowPic 


pascal 


void SetWRefCon 
long GetWRefCon 


pascal 
pascal 


pascal short GetWVariant 
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(WindowPtr theWindow, PicHandle pic); 


PicHandle GetWindowPic 


(WindowPtr theWindow) ; 
(WindowPtr theWindow, long data); 
(WindowPtr theWindow) ; 


(WindowPtr theWindow) ; 
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DragGrayRgnProcPtr actionProc) ; 
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Manipulating the Desktop 


pascal void SetDeskCPat 


#define GetGrayRgn () 


pascal void GetCWMgrPort 


pascal void GetWMgrPort 


(PixPatHandle deskPixPat) ; 
(* (RgnHandle* OX09EE) ) 
(CGrafPtr *wMgrCPort) ; 





(GrafPtr *wPort); 


Manipulating Window Color Information 


pascal void SetWinColor 


pascal Boolean GetAuxWin 


Low-Level Routines 


pascal 
pascal 
pascal 
pascal 
pascal 


pascal 


pascal 


pascal 


Bool 
void 
void 
void 
void 


void 


void 


void 


ean CheckUpdate 
ClipAbove 
SaveOld 
DrawNew 
PaintOne 


PaintBehind 


CalcVis 
CalcVisBehind 


Application-Defined Routine 


The Window Definition Function 


pascal long MyWindow 


(WindowPtr theWindow, 
WCTabHandle newColorTable) ; 


(WindowPtr theWindow, AuxWinHandle *awHndl)j; 





(WindowPeek 
(WindowPeek 
(WindowPeek 
(WindowPeek 
(WindowPeek 





(EventRecord *theEvent) ; 


window; ) 
window) ; 


window, Boolean update) ; 





window, RgnHandle clobberedRgn) ; 


startWindow, 


RgnHandle clobberedRgn) ; 


(WindowPeek 
(WindowPeek 


window) ; 


startWindow, 


RgnHandle clobberedRgn) ; 


(short varCode, WindowPtr theWindow, 


short message, long param) ; 
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Data Types 


Window Record and Color Window Record Data Structure 


0 
108 
110 
111 
112 
113 
114 
118 
122 
126 
130 
134 
138 
140 
144 
148 
152 


windowPort 
windowKind 
wVisible 
wHilited 
wGoAway 
wZoom 
structRgn 
contRgn 
updateRgn 
windowDef 
wDataHandle 
wTitleHandle 
wlitleWidth 
wControlList 
nextWindow 
windowPic 
wRefCon 





108 bytes 
word 
byte 
byte 
byte 
byte 
long 
long 
long 
long 
long 
long 
word 
long 
long 
long 
long 


Window State Data Structure 


0 
8 


userState 
stdState 


8 bytes 
8 bytes 


window’s graphics port 

how window was created 

visibility status 

highlighted status 

presence of close box 

presence of zoom box 

handle to structure region 

handle to content region 

handle to update region 

handle to window definition function 
handle to window state data record 
handle to window’s title 

title width in pixels 

handle to window’s control list 
pointer to next window in window list 
handle to picture for updates 
reference constant field 


user state rectangle 
standard state rectangle 


Window Color Information Table Data Structure 


0 
4 
6 
8 


ctSeed 
ctFlags 
ctSize 
ctTable 


long 
word 
word 
variable 


ID number for table 

flags word 

number of entries minus 1 

a series of color specification records (8 bytes each) 


Auxiliary Window Record Data Structure 
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awNext 
awOwner 
awCTable 
dialogCItem 
awFlags 
awResrv 
awRefCon 


long 
long 
long 
long 
long 
long 
long 


handle to next window in chain 

pointer to associated window record 
handle to window color information table 
handle to dialog color structures 

handle for QuickDraw 

reserved 

user constant 
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Global Variables 


AuxWinHead 
CurActivate 
CurDeactive 
DeskHook 
DeskPattern 
DragHook 


DragPattern 
GrayRgn 
OldContent 
OldStructure 
PaintWhite 
SaveUpdate 
SaveVisRgn 
WindowList 
WMgrPort 


Handle to beginning of auxiliary window list. 
Pointer to window to receive activate event. 
Pointer to window to receive deactivate event. 
Address of procedure for painting desktop. 
Pattern in which desktop is painted (8 bytes). 


Address of optional procedure to execute during TrackGoAway, TrackBox, 
DragWindow, GrowWindow, and DragGrayRgn. 


Pattern of dragged region’s outline (8 bytes). 
Handle to desktop region. 

Handle to saved content region. 

Handle to saved structure region. 


Flag indicating whether to paint window white before update event (2 bytes). 


Flag indicating whether to generate update events (2 bytes). 
Handle to saved visible region. 

Pointer to first window in window list. 

Pointer to Window Manager port. 
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CHAPTER 5 


Control Manager 


This chapter describes how your application can use the Control Manager to create 

and manage controls. Controls are onscreen objects that the user can manipulate with 
the mouse. By manipulating controls, the user can take an immediate action or change 
settings to modify a future action. For example, a scroll bar control allows a user to 
immediately change the portion of the document that your application displays, whereas 
a pop-up menu control for baud rate might allow the user to change the rate by which 
your application handles subsequent data transmissions. 


Read this chapter to learn how and when to implement controls. Virtually all applica- 
tions need to implement controls, at least in the form of scroll bars for document 
windows. You use Control Manager routines, resources, and data structures to imple- 
ment scroll bars in your application’s document windows. 


The other standard Macintosh controls are buttons, checkboxes, radio buttons, and 
pop-up menus. You can use the Control Manager to create and manage these controls, 
too. Alternatively, you can use the Dialog Manager to implement these controls in alert 
boxes and dialog boxes more easily. (You typically use an alert box to warn a user of 
an unusual situation, and you typically use a dialog box to ask the user for information 
necessary to carry out a command.) The chapter “Dialog Manager” in this book 
describes in detail how to implement controls in alert and dialog boxes. However, in 
certain situations—for instance, when you need to implement highly complex dialog 
boxes—you may want to use Control Manager routines to manage these types of 
controls directly; read this chapter for information on how to do so. 


For scrolling lists of graphic or textual information (similar to the list of files that system 
software presents after the user chooses the Open command from the File menu), your 
application can use the List Manager to implement the scroll bars. See the chapter “List 
Manager” in Inside Macintosh: More Macintosh Toolbox for more information. 


The Control Manager offers routines for automatically handling user-generated 

mouse events in controls and redrawing controls in response to update events. For 
further information about events and event handling, see the chapter “Event Manager” 
in this book. 


You typically use a control resource—a resource of type 'CNTL'—to specify the type, 
size, location, and other attributes of a control. See the chapter “Introduction to the 
Macintosh Toolbox” in this book for general information about resources; detailed 
information about the Resource Manager and its routines is provided in the chapter 
“Resource Manager” in Inside Macintosh: More Macintosh Toolbox. 


Every control you create must be associated with a particular window. All of the controls 
for a window are stored in a control list referenced by the window’s window record. See 
the chapter “Window Manager” in this book for general information about windows. 
(When you use the Dialog Manager to implement a control, the Dialog Manager 
associates it with its respective dialog box or alert box, as described in the chapter 
“Dialog Manager.”) 
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This chapter provides an introduction to the use of controls, and then discusses how 
you can 


create and display controls 

determine whether mouse-down events have occurred in controls 
respond to mouse-down events in controls 

change the settings in controls 

use scroll bars to move a document in a window 

move and resize controls for a window 


define your own control definition function to create nonstandard controls 


Introduction to Controls 


The Control Manager provides several standard controls. Figure 5-1 illustrates these 
standard controls: buttons, checkboxes, radio buttons, pop-up menus, and scroll bars. 
You can also design and implement your own custom controls. 


Figure 5-1 Standard controls provided by the Control Manager 
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Buttons, checkboxes, and radio buttons are the simplest controls. They consist of only a 
title and an outline shape, and they respond to only mouse clicks. A pop-up menu is 
slightly more complex. This control has a menu attached to its title, and it must respond 
when the user drags the cursor across the menu. A scroll bar, because it consists of 
different parts that behave differently, is the most complex of the standard controls. Even 
though a scroll bar has several parts, it is still only one control. 


The Control Manager displays these standard controls in colors that provide aesthetic 
consistency across all monitors, from black-and-white displays to 8-bit color displays. 
To ensure consistency across applications, you generally shouldn’t change the default 
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colors of controls, although the Control Manager does allow you to do so with the 
SetControlColor procedure (described on page 5-101) or the control color table 
resource (described on page 5-121). 


Standard controls and common custom controls are described in the next 
several sections. 


Buttons 


Buttons appear on the screen as rounded rectangles with a title centered inside. When 
the user clicks a button, your application should perform the action described by the 
button title. Typically, buttons allow the user to perform actions instantaneously—for 
example, completing the operations defined by a dialog box or acknowledging an error 
message in an alert box. 


Make your buttons large enough to surround their titles. In every window or dialog box 
in which you display buttons, you should designate one button as the default button by 
drawing a thick black outline around it (as shown in Figure 5-2). Your application should 
respond to key-down events involving the Enter and Return keys as if the user had 
clicked the default button. (In your alert boxes, the Dialog Manager automatically 
outlines the default button; you must outline the default button in your dialog boxes.) 


Figure 5-2 A default button 


You normally use buttons in alert boxes and dialog boxes. See the chapter “Dialog 
Manager” for additional details about where to display buttons, what to title them, how 
to respond to events involving them, and how to draw an outline around them. 


Checkboxes 


Checkboxes provide alternative choices. Typically you use checkboxes in dialog boxes so 
that users can specify information necessary for completing a command. Checkboxes act 
like toggle switches, turning a setting either off or on. Use checkboxes to indicate one or 
more options that must be either off or on. A checkbox appears as a small square with a 
title alongside it; use the Control Manager procedure Set Cont rolValue to place an X 
in the box when the user selects it by clicking it on and to remove the X when the user 
deselects it by clicking it off. Figure 5-3 shows a selected checkbox. 


Figure 5-3 A selected checkbox 
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When you design a dialog box, you can include any number of checkboxes—including 
only one. Checkboxes are independent of each other, even when they offer related 
options. Within a dialog box, it’s a good idea to group sets of related checkboxes and to 
provide some visual demarcation between different groups. 


Each checkbox has a title. It can be very difficult to title the option in an unambiguous 
way. The title should reflect two clearly opposite states. For example, in a Finder’s Info 
window, a checkbox provides the option to lock a file. The checkbox is titled simply 
Locked. The clearly opposite state, when the option is off, is unlocked. 


If you can’t devise a checkbox title that clearly implies an opposite state, you might be 
better off using two radio buttons. With two radio buttons, you can use two titles, 
thereby clarifying the states. 


Checkboxes are frequently used in dialog boxes to set or modify future actions instead of 
specifying actions to be taken immediately. See the chapter “Dialog Manager” in this 
book for a detailed discussion of how and where to display checkboxes in dialog boxes. 


Radio Buttons 


Like checkboxes, radio buttons retain and display an on-or-off setting. You organize 
radio buttons in a group to offer a choice among several alternatives—typically, inside a 
dialog box. Radio buttons are small circles; when the user clicks a radio button to turn it 
on, use the Control Manager procedure Set Cont rolValue to fill the radio button with 
a small black dot. The user can have only one radio button setting in effect at one time. 

In other words, radio buttons are mutually exclusive. However, the Control Manager 
cannot determine how your radio buttons are grouped; therefore, when the user turns on 
one radio button, it is up to your application to use Set Cont rolValue to turn off the 
others in that group. 


A set of radio buttons normally has two to seven items; each set must always have at 
least two radio buttons. Each set of radio buttons must have a label that identifies the 
kind of choices the group offers. Also, each button must have a title that identifies what 
the radio button does. This title can be a few words or a phrase. A set of radio buttons is 
never dynamic—that is, its contents should never change according to the context. (If you 
need to display more than seven items, or if the items change as the context changes, you 
should use a pop-up menu instead.) 


Radio buttons represent choices that are related but not necessarily opposite. For 
example, a pair of radio buttons may provide a choice between using the modem port or 
the printer port, as shown in Figure 5-1 on page 5-4. If more than one set of radio buttons 
is visible at one time, you need to demarcate the sets from one another. For example, you 
can draw a dotted line around a set of radio buttons to separate it from other elements in 
a dialog box. 


Pop-Up Menus 


Pop-up menus, introduced in the chapter “Menu Manager” in this book, provide the 
user with a simple way to choose from among a list of choices without having to move 
the cursor to the menu bar. As an alternative to a group of radio buttons, a pop-up menu 


Introduction to Controls 


CHAPTER 5 


Control Manager 


is particularly useful for specifying a group of settings or values that number five or 
more, or whose settings or values might change. Like the items in a set of radio buttons, 
the items in a pop-up menu are mutually exclusive—that is, only one choice from the 
menu can be in effect at any time. Figure 5-8 on page 5-12 illustrates the choices available 
in a pop-up menu that has been selected by the user. 


Never use a pop-up menu as a way to provide the user with commands. Pop-up 
menus should not list actions (that is, verbs); instead, they should list attributes (that 
is, adjectives) or settings from which the user can choose one option. 


Scroll Bars 


Scroll bars change what portion of a document the user can view within the document's 
window. A scroll bar is a light gray rectangle with scroll arrows at each end. Inside the 
scroll bar is a square called the scroll box. The rest of the scroll bar is called the gray 
area. Windows can have a horizontal scroll bar, a vertical scroll bar, or both. A vertical 
scroll bar lies along the right side of a window. A horizontal scroll bar runs along the 
bottom of a window. Figure 5-4 shows the parts of a scroll bar. 


Figure 5-4 A vertical scroll bar 





If the user drags the scroll box, clicks a scroll arrow, or clicks anywhere in the gray area, 
your application “moves” the document accordingly; use Control Manager routines as 
appropriate to move the scroll box. Figure 5-5 illustrates, and the next few sections 
explain, several key behaviors of a scroll bar. 


A scroll bar represents the entire document in one dimension, top to bottom or right to 
left. The scroll box shows the position, relative to the whole document, of the visible 
portion of the document. If the scroll box is halfway between the top and bottom of the 
scroll bar, then what the user sees should be about halfway through the document. Use 
the SetControlValue or SetCont rolMaximum procedure to move the scroll box 
whenever your application resizes a window and whenever it scrolls through a 
document for any reason other than responding to the user dragging the scroll box. 
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After the user drags the scroll box, the Control Manager redraws the scroll box in its new 
position. You then use the Get Cont rolValue function to determine the position of the 
scroll box, and you display the appropriate portion of the document. By dragging the 
scroll box, the user can move quickly through the document. For example, to see the 
beginning of the document, the user drags the scroll box to the top of the scroll bar. Your 
application then scrolls to the top of the document. 


At either end of the scroll bar are scroll arrows that indicate the direction of movement 
through the document. For instance, when the user clicks the top scroll arrow, your 

application needs to move toward the beginning of the document. Thus, the document 
moves down, seemingly in the opposite direction. By clicking the scroll arrow, the user 
tells your application, “Show me more of the document that’s hidden in this direction.” 


Your application uses the Set Cont rolValue procedure to move the scroll box in the 
direction of the arrow being clicked. In this way, the scroll box continues to represent 
the approximate position of the visible part of the document in relation to the whole 
document. For example, when the user clicks the top scroll arrow, you move the 
document down to bring more of the top of the document into view, and you move the 
scroll box up, as illustrated in Figure 5-5. 


Figure 5-5 Using the scroll box and scroll arrows 


Deesunn art 





Docu ert 
ecroll dracon 


a 


1 


Introduction to Controls 


CHAPTER 5 


Control Manager 


Each click of a scroll arrow should move the document a distance of one unit in the 
chosen direction. Your application determines what one unit equals. For example, a 
word processor should move one line of text for each click in the arrow. A spreadsheet 
should move one row or one column, depending on the direction of the arrow. To ensure 
smooth scrolling effects, it’s usually best to specify the same size units within a 
document. When the user holds down the mouse button while the cursor is in a scroll 
arrow, your application should continuously scroll through the document in the 
indicated direction until the user releases the mouse button or your application has 
scrolled as far as possible. 


The rest of the area within the scroll bar—excluding the scroll box and the scroll arrows— 
is called the gray area. When the user clicks the gray area of a scroll bar, your application 
should move the displayed area of the document by an entire window of information 
minus one scroll unit. For example, if the window displays 15 lines of text and the user 
clicks the gray area below the scroll box, your application should move the document up 
14 lines so that the bottom line of the previous view appears at the top of the new view. 
(This retained line helps the user see the newly displayed material in context.) You must 
also move the scroll box an appropriate distance in that direction. For example, when the 
user clicks the gray area below the scroll box, move the document view by one window 
toward the bottom of the document and use Set Cont rolValue to move the scroll box 
accordingly. 


When your application scrolls through a document—for example, when the user 
manipulates a scroll bar—your application must move the document’s coordinate space 
in relation to the window’s coordinate space. Your application uses the scroll box to 
indicate the location of the top of the displayed portion of the document relative to the 
rest of the document. 


For example, if a text window contains 15 lines of text and the user scrolls 30 lines from 
the top of the document, the scroll box should be set to a value of 30. The window 
displays all of the lines between line 30 and line 45, as shown in Figure 5-6 on the next 
page. The scroll box always indicates the displacement between the beginning of the 
document and the top of the displayed portion of the document. 


To prevent the user from scrolling past the edge of the document and seeing a blank 
window, you should—for a vertical scroll bar—allow the document to scroll no farther 
than the length of the document minus the height of the window, excluding the 
15-pixel-deep region for the horizontal scroll bar at the bottom edge of the window. 
Likewise, for a horizontal scroll bar, you should allow the document to scroll no farther 
than the width of the document minus the width of the window—here, too, excluding 
the 15-pixel-wide region for the vertical scroll bar at the right edge of the window. 
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Figure 5-6 Spatial relations between a document and a window, and their representation by 
a scroll bar 
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For example, the document shown in Figure 5-6 is 105 lines long. So that the last 15 lines 
will fill the window when the user scrolls to the end of the document, the application 
does not scroll beyond 90 lines. Because the user has scrolled to line 30 of a maximum 
90 lines, the scroll box appears a third of the way down the scroll bar. 


“Scrolling Through a Document” beginning on page 5-43 describes in detail how to 
scroll through a document in a window. 
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Other Controls 


If you need controls other than the standard ones provided by the Control Manager, 
you can design and implement your own. Typically, the only types of controls you 
might need to implement are sliders or dials. Sliders and dials (which differ only in 
appearance) are similar to scroll bars in that they graphically represent a range of 
values that a user can set. Use an indicator—such as a sliding switch or a dial needle— 
to indicate the current setting for the control and to let the user set its value. (For scroll 
bars, the scroll box is the indicator.) 


If you want to display a value not under the user’s direct control (for example, the 
amount of free space remaining on a disk), you should use a status bar or other type 
of graphic instead of a slider or dial. 


Figure 5-7 illustrates several custom controls, which are used for purposes such as 
setting the speaker volume, the gray-scale saturation level, and the relative position 
of a slide within a presentation. As in this figure, be sure to include meaningful labels 
that indicate the range and the direction of your control's indicator. 


Figure 5-7 Custom slider controls 
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A scroll bar is a slider representing the entire contents of a window, and the user uses the 
scroll box to move to a specific location in that content. Don’t use scroll bars to represent 

any other concept (for instance, changing a setting). Otherwise, your departure from the 

consistent Macintosh interface might confuse the user. 


Active and Inactive Controls 


You can make a control become either active or inactive. Figure 5-8 on the next page 
shows how the TrackControl function (which you use in response to a mouse-down 
event in a control) gives visual feedback when the user moves the cursor to an active 
control and presses the mouse button. In particular, TrackCont rol responds to mouse- 
down events in active controls by 


m displaying buttons in inverse video 

m drawing checkboxes and radio buttons with heavier lines 
highlighting the titles of and displaying the items in pop-up menus 
highlighting scroll arrows 


moving outlines of scroll boxes when users drag them 
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Figure 5-8 Visual feedback for user selection of active controls 
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Your application, in turn, should respond appropriately to mouse events involving 
active controls. Most often, your application waits until the user releases the mouse 
button before taking any action; as long as the user holds down the mouse button when 
the cursor is over a control, you typically let TrackCont rol react to the mouse-down 
event; TrackCont rol then informs your application the moment the user releases the 
mouse button when the cursor is over an active control. 


As soon as the user releases the mouse button, your application should 
m perform the task identified by the button title when the cursor is over an active button 


m toggle the value of the checkbox when the cursor is over an active checkbox (The 
Control Manager then draws or removes the checkmark, as appropriate.) 


m turn on the radio button and turn off all other radio buttons in the group when the 
cursor is over an active radio button 


m use the new setting chosen by the user when the cursor is over an active pop-up menu 


m show more of the document in the direction of the scroll arrow when the cursor is 
over the scroll arrow or gray area of an active scroll bar, and move the scroll box 
accordingly 


m determine where the user has dragged the scroll box when the cursor is over the scroll 
box and then display the corresponding portion of the document 


Sometimes your application should respond even before the user releases the mouse 
button—that is, your application should undertake some continuous action as long as 


Introduction to Controls 


CHAPTER 5 


Control Manager 


the user holds down the mouse button when the cursor is in an active control. Most 
typically, when the user moves the cursor to a scroll arrow or gray area and then holds 
down the mouse button, your application should continuously scroll through the 
document until the user releases the mouse button or until the user can’t scroll any 
farther. To perform this kind of action, you define an action procedure and specify it to 
TrackControl; TrackControl calls your action procedure as long as the user holds 
down the mouse button. 


Whenever it is inappropriate for your application to a respond to a mouse-down event in 
a control, you should make it inactive. An inactive control is one that the user can’t use 
because it has no meaning or effect in the current context—for example, the scroll bars 

in an empty window. The Control Manager continues to display an inactive control so 
that it remains visible, but in a manner that indicates its state to the user. As shown in 
Figure 5-9, the Control Manager dims inactive buttons, checkboxes, radio buttons, and 
pop-up menus, and it lightens the gray area and removes the scroll box from inactive 
scroll bars. 


Figure 5-9 Inactive controls 
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You can use the HiliteControl procedure to make any control inactive and then 
active again. Except for scroll bars (which you should hide using the HideControl 
procedure), you should use HiliteControl to make all other controls inactive when 
their windows are not frontmost. You typically use controls other than scroll bars in 
dialog boxes. See the chapter “Dialog Manager” in this book for a discussion of how to 
make buttons, radio buttons, checkboxes, and pop-up menus inactive and active. 


You make scroll bars inactive when the document is smaller than the window in which 
you display it. To make a scroll bar inactive, you typically use the Set ControlMaximum 
procedure to make the scroll bar’s maximum value equal to its minimum value, in which 
case the Control Manager automatically makes the scroll bar inactive. To make it active 
again, you typically use SetControlMaximum to make its maximum value larger than 
its minimum value. 
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The Control Definition Function 


A control definition function determines how a control generally looks and behaves. 
Various Control Manager routines call a control definition function whenever they need 
to perform some control-dependent action, such as drawing the control on the screen. 


Control definition functions are stored as resources of type 'CDEF'. The System file 
includes three standard control definition functions, stored with resource IDs of 0, 1, 
and 63. The 'CDEF' resource with resource ID 0 defines the look and behavior of 
buttons, checkboxes, and radio buttons; the 'CDEF' resource with resource ID 1 defines 
the look and behavior of scroll bars; and the 'CDEF' resource with resource ID 63 
defines the look and behavior of pop-up menus. (If you want to define nonstandard 
controls, you'll have to write control definition functions for them, as described in 
“Defining Your Own Control Definition Function” beginning on page 5-109.) 











Just as a window definition function can describe variations of the same basic window, a 
control definition function can use a variation code to describe variations of the same 
basic control. You specify a particular control with a control definition ID. The control 
definition ID is an integer that contains the resource ID of the control definition function 
in its upper 12 bits and a variation code in its lower 4 bits. For a given resource ID and 
variation code, the control definition ID is derived as follows: 


control definition ID = 16 * ('CDEF' resource ID) + variation code 


For example, buttons, checkboxes, and radio buttons all use the standard control 
definition function with resource ID 0; because they have variation codes of 0, 1, 
and 2, respectively, their respective control definition IDs are 0, 1, and 2. 


You can use these constants to define the controls provided by the standard control 
definition functions: 








Control 
Constant definition ID Control 
pushButProc 0 Button 
checkBoxProc 1 Checkbox 
radioButProc Zs Radio button 
scrollBarProc 16 Scroll bar 
popupMenuProc 1008 Pop-up menu 





The control definition function for scroll bars figures out whether a scroll bar is vertical 
or horizontal from a rectangle you specify when you create the control. 


About the Control Manager 


5-14 


You can use the Control Manager to 
m create and dispose of controls 


m display, update, and hide controls 
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m change the size, location, and appearance of controls 
™ monitor and respond to the user’s operation of a control 
m determine and change the settings and other attributes of a control 


Your application performs these actions by calling the appropriate Control Manager 
routines. The Control Manager carries out the actual operations, but it’s up to you to 
decide when, where, and how to carry these out. 


Using the Control Manager 


To implement a control, you generally 
m use a control resource (that is, a resource of type 'CNTL"') to describe the control 
m create and display the control 


m determine when the user presses, clicks, or holds down the mouse button while the 
cursor is in the control 


m respond as appropriate to events involving the control—for example, by displaying a 
different portion of the document when the user manipulates a scroll bar 


m respond as appropriate to other events in windows that include controls—for 
example, by moving and resizing a scroll bar when the user resizes a window, or by 
hiding one window’s scroll bars when the user makes a different window active 


These tasks are explained in greater detail in the rest of this chapter. 


Before using the Control Manager, you must initialize QuickDraw, the Font Manager, 
and the Window Manager, in that order, by using the InitGraf, InitFonts, and 
InitWindows procedures. (See Inside Macintosh: Imaging for information about 
InitGraf and InitFonts; see the chapter “Window Manager” in this book for 
information about InitWindows.) 


Creating and Displaying a Control 


To create a control in one of your application’s windows, use the Get NewCont rol or 
NewCont rol function. You should usually use Get NewCont rol, which takes 
information about the control from a control resource (that is, a'CNTL' resource) ina 
resource file. Like window resources, control resources isolate descriptive information 
from your application code for ease of modification—especially for translation to other 
languages. The rest of this section describes how to use GetNewCont rol. Although it’s 
generally not recommended, you can also use the NewCont rol function and pass it the 
necessary descriptive information in individual parameters instead of using a control 
resource. The NewCont rol function is described on page 5-82. 


When you use GetNewCont rol, you pass it the resource ID of the control resource, and 
you pass it a pointer to a window. The function then creates a data structure (called a 
control record) of type Cont rolRecord from the information in the control resource, 
adds the control record to the control list for your window, and returns as its function 
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result a handle to the control. (You use a control’s handle when referring to the control in 
most other Control Manager routines; when you create scroll bars or pop-up menus for a 
window, you should store their handles in one of your application’s own data structures 
for later reference.) 


When you specify in the control resource that a control is initially visible and you use the 
GetNewControl function, the Control Manager uses the control’s control definition 
function to draw the control inside its window. The Control Manager draws the control 
immediately, without using your window’s standard updating mechanism. If you 
specify that a control is invisible, you can use the ShowCont rol procedure when you 
want to draw the control. Again, the Control Manager draws the control without using 
your window’s standard updating mechanism. (Of course, even when the Control 
Manager draws the control, it might be completely or partially obscured from the user 
by overlapping windows or other objects.) 


When your application receives an update event for a window that contains controls, 
you use the UpdateControls procedure in your application’s standard window- 
updating code to redraw all the controls in the update region of the window. 


Note 

When you use the Dialog Manager to implement buttons, radio buttons, 
checkboxes, or pop-up menus in alert boxes and dialog boxes, Dialog 
Manager routines automatically use Control Manager routines to create 
and update these controls for you. If you implement any controls other 
than buttons, radio buttons, checkboxes, and pop-up menus in alert or 
dialog boxes—and whenever you implement any controls (scroll bars, 
for example) in your application’s windows—you must explicitly use 
either the GetNewCont rol or the NewCont rol function to create the 
controls. You must always use the UpdateControls procedure to 
update controls you put in your own windows. # 


When you use the Window Manager procedure DisposeWindow or CloseWindow to 
remove a window, either procedure automatically removes all controls associated with 
the window and releases the memory they occupy. 


When you no longer need a control in a window that you want to keep, you can use the 
DisposeControl procedure, described on page 5-108, to remove it from the screen, 
delete it from its window’s control list, and release the control record and all other 
associated data structures from memory. You can use the Kil1 Controls procedure, 
described on page 5-108, to dispose of all of a window’s controls at once. 


The next section, “Creating a Button, Checkbox, or Radio Button,” provides a general 
discussion of the control resource as well as a more detailed description of the use of the 
control resource to specify buttons, checkboxes, and radio buttons in your application’s 
windows. The two following sections, “Creating Scroll Bars” (beginning on page 5-21) 
and “Creating a Pop-Up Menu” (beginning on page 5-25), describe those elements of the 
control resource that differ from the control resources for buttons, checkboxes, and radio 
buttons. “Updating a Control” beginning on page 5-29 then offers an example of how 
you can use the UpdateControls procedure within your window-updating code. 
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Note 

For the Control Manager to draw a control properly inside a window, 
the window must have its upper-left corner at local coordinates (0,0). If 
you use the QuickDraw procedure Set Origin to change a window’s 
local coordinate system, be sure to change it back—so that the upper-left 
corner is again at (0,0)—before drawing any of its controls. Because 
many Control Manager routines can (at least potentially) redraw a 
control, the safest policy after changing a window’s local coordinate 
system is to change the coordinate system back before calling any 
Control Manager routine. 


Creating a Button, Checkbox, or Radio Button 


Figure 5-10 shows a simple example of a button placed in a window of type 
noGrowDocProc—which you normally use to create a modeless dialog box. 
Although you usually use the Dialog Manager to create dialog boxes and their 
buttons, sometimes you might use the Window Manager and the Control Manager 
instead. The chapter “Dialog Manager” in this book explains why the use of the 
Window and Control Managers is sometimes preferable for this purpose. 


Figure 5-10 A button in a simple window 
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Listing 5-1 shows an application-defined routine, MyCreatePlaySoundsWindow, that 
uses the Get NewCont rol function to create the button shown in Figure 5-10. 


Listing 5-1 Creating a button for a window 


FUNCTION MyCreatePlaySoundsWindow: OSErr; 


VAR 
myWindow: WindowPtr; 
BEGIN 
MyCreatePlaySoundsWindow := noErr; 
myWindow := GetNewWindow(rPlaySoundsModelessWindow, NIL, POINTER(-1)); 
IF myWindow <> NIL THEN 
BEGIN 





{use the window's refCon to identify this window} 
SetWRefCon (myWindow, LongInt (kKMyPlaySoundsWindow) ) ; 
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SetPort (myWindow) ; 
gMyPlayButtonCtlHandle := GetNewControl(rPlayButton, myWindow) ; 


IF 


END 
ELSE 


(gMyPlayButtonCtlHandle = NIL) THEN 
MyCreatePlaySoundsWindow := kControlErr; 











MyCreatePlaySoundsWindow := kNoSoundWindow; 


END; 


5-18 


The MyCreatePlaySoundsWindow routine begins by using the Window Manager 
function Get NewWindow to create a window; a pointer to that window is passed to 
GetNewControl. Note that, as explained in the chapter “Dialog Manager” in this book, 
you could create a modeless dialog box more easily by using the Dialog Manager 
function Get NewDialog and specifying its controls in an item list ('DITL") resource. 


For the resource ID of a control resource, the MyCreateP laySoundsWindow routine 
defines an rPlayButton constant, which it passes to the GetNewCont rol function. 
Listing 5-2 shows how this control resource appears in Rez input format. 


Listing 5-2 Rez input for a control resource 


resource 'CNTL' (rPlayButton, preload, purgeable) { 
{87, 187, 107, 247}, /*rectangle*/ 
0, /*initial setting*/ 
visible, /*make control visible*/ 
1, /*maximum setting*/ 
0, /*minimum setting*/ 
pushButProc, /*control definition ID*/ 
0, /*reference value*/ 
"Play" /*title*/ 





7 
You supply the following information in the control resource for a button, checkbox, 
radio button, or scroll bar: 


m arectangle, specified by coordinates local to the window, that determines the control’s 
size and location 


m the initial setting for the control 


a constant (either visibleorinvisible) that specifies whether the control should 
be drawn on the screen immediately 


the maximum setting for the control 
the minimum setting for the control 
the control definition ID 


a reference value, which your application may use for any purpose 


the title of the control; or, for scroll bars, an empty string 
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As explained in “Creating a Pop-Up Menu” beginning on page 5-25, the values you 
supply in a control resource for a pop-up menu differ from those you specify for other 
buttons, checkboxes, radio buttons, and scroll bars. 


Buttons are drawn to fit the rectangle exactly. To allow for the tallest characters in 
the system font, there should be at least a 20-point difference between the top and 
bottom coordinates of the rectangle. Listing 5-2 uses a rectangle with coordinates 
(87,187,107,247) to describe the size and location of the control within the window. 
Remember that the Control Manager will not draw controls properly unless the 
upper-left corner of the window coincides with the coordinates (0,0). 


In Listing 5-2, the initial and minimum settings for the button are 0 and the maximum 
setting is 1. In control resources for buttons, checkboxes, and radio buttons, supply these 
values as the initial settings: 


a For buttons, which don’t retain a setting, specify a value of 0 for the initial and 
minimum settings and 1 for the maximum setting. 


m For checkboxes and radio buttons, which retain an on-or-off setting, specify a value of 
0 when you want to the control to be initially off. To turn a checkbox or radio button 
on, assign it an initial setting of 1. In response, the Control Manager places an X ina 
checkbox or a black dot in a radio button. 


Because the visible identifier is specified in this example, the control is drawn 
immediately in its window. If you use the invisible identifier, your control is not 
drawn until your application uses the ShowCont rol procedure. When you want to 
make a visible control invisible, you can use the HideCont rol procedure. 


In Listing 5-2, the maximum setting for the button is 1, which you, too, should specify in 
your control resources as the maximum setting for buttons, checkboxes, and radio 
buttons. In Listing 5-2, the minimum setting for the button is 0, which you, too, should 
specify in your control resources as the minimum setting for buttons, checkboxes, and 
radio buttons. 


In Listing 5-2, the pushButProc constant is used to specify the control definition ID. 
Use the checkBoxProc constant to specify a checkbox and the radioButProc 
constant to specify a radio button. 





Listing 5-2 specifies a reference value of 0. Your application can use this value for any 
purpose (except when you add the popupUseAddResMenu variation code to the 
popupMenuProc control definition function, as described in “Creating a Pop-Up Menu” 
beginning on page 5-25). 


Finally, the string "Play" is specified as the title of the control. Buttons, checkboxes, 
and radio buttons require a title that communicates their purpose to the user. (The 
chapter “Dialog Manager” in this book offers extensive guidelines on appropriate titles 
for buttons.) 


When specifying a title, make sure it fits in the control’s rectangle; otherwise, the 
Control Manager truncates the title. For example, it truncates the titles of checkboxes 
and radio buttons on the right in Roman scripts, and it centers and truncates both ends 
of button titles. 
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If you localize your application for use with worldwide versions of system software, the 
titles may become longer or shorter. Translated text is often 50 percent longer than U.S. 
English text. You may need to resize your controls to accommodate the translated text. 


By default, the Control Manager displays control titles in the system font. To make it 
easier to localize your application for use with worldwide versions of system software, 
you should not change the font. Do not use a smaller font, such as 9-point Geneva; some 
script systems, such as KanjiTalk, require 12-point fonts. You can spare yourself future 
localization effort by leaving all control titles in the system font. 


Follow book-title style when you capitalize control titles. In general, capitalize one-word 
titles and capitalize nouns, adjectives, verbs, and prepositions of four or more letters in 
multiple-word titles. You usually don’t capitalize words such as in, an, or and. For 
capitalization rules, see the Apple Publications Style Guide, available from APDA. 


The Control Manager allows button, checkbox, and radio button titles of multiple lines. 
When specifying a multiple-line title, end each line with the ASCII character code $0D 
(carriage return). If the control is a button, each line is horizontally centered, and the 
font leading is inserted between lines. (The height of each line is equal to the distance 
from the ascent line to the descent line plus the leading of the font used. Be sure to make 
the total height of the rectangle greater than the number of lines times this height.) If 
the control is a checkbox or a radio button, the text is justified as appropriate for the 
user’s current script system, and the checkbox or button is vertically centered within 

its rectangle. 


Figure 5-11 shows the Play Sounds window with four additional controls: radio buttons 
titled Droplet, Quack, Simple Beep, and Wild Eep. 


Figure 5-11 Radio buttons in a simple window 
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Only one of these radio buttons can be on at a time. Listing 5-3 initially sets the Droplet 
radio button to 1, turning it on by default. This listing also shows the control resources 
for the other buttons, all initially set to 0 to turn them off. 


For a checkbox or a radio button, always allow at least a 16-point difference between the 
top and bottom coordinates of its rectangle to accommodate the tallest characters in the 
system font. 
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Listing 5-3 Rez input for the control resources of radio buttons 


resource 'CNTL' (cDroplet, preload, purgeable) { 
{13, 23, 31, 142},/*rectangle of control*/ 





ales /*initial setting*/ 
visible, /*make control visible*/ 
dl /*maximum setting*/ 

Oy /*minimum setting*/ 
radioButProc, /*control definition ID*/ 
0 /*reference value*/ 
"Droplet" /*control title*/ 


}; 

resource 'CNTL' (cQuack, preload, purgeable) { 
{31, 23, 49, 142},/*rectangle of control*/ 
0, /*initial setting*/ 





visible, 1, 0, radioButProc, 0, "Quack"}; 


resource 'CNTL' (cSimpleBeep, preload, purgeable) { 
{49, 23, 67, 142},/*rectangle of control*/ 
0, /*initial setting*/ 








visible, 1, 0, radioButProc, 0, "Simple Beep"}; 


resource 'CNTL' (cWildEep, preload, purgeable) { 
{67, 23, 85, 142},/*rectangle of control*/ 
0, /*initial setting*/ 








visible, 1, 0, radioButProc, 0, "Wild Eep"}; 


Creating Scroll Bars 


When you define the control resource for a scroll bar, specify the scrollBarProc 
constant for the control definition ID. Typically, you make the scroll bar invisible and 
specify an initial value of 0, a minimum value of 0, and a maximum value of 0, and you 
supply an empty string for the title. 


After you create a window, use the GetNewCont rol function to create the scroll bar 
you've defined in the control resource and to attach that scroll bar to the window. Use 
the MoveControl, SizeControl, SetControlMaximum, and SetControlValue 
procedures to adjust the location, size, and settings of the scroll bars, and then use the 
ShowControl procedure to display the scroll bars. 


In your window-handling code, make the maximum setting the maximum area you 
want to allow the user to scroll. Most applications allow the user to drag the size box and 
click the zoom box to change the size of windows, and they allow the user to add 
information to and remove it from documents. To allow users to perform these actions, 
your application needs to calculate a changing maximum setting based upon the 
document’s current size and its window’s current size. For new documents that have no 


Using the Control Manager 5-21 


CHAPTER 5 


Control Manager 


content to scroll to, assign an initial value of 0 as the maximum setting in the control 
resource; the control definition function automatically makes a scroll bar inactive when 
its minimum and maximum settings are identical. Thereafter, your window-handling 
routines should set and maintain the maximum setting, as described in “Determining 
and Changing Control Settings” beginning on page 5-37. 

By convention, a scroll bar is 16 pixels wide, so there should be a 16-point difference 
between the left and right coordinates of a vertical scroll bar’s rectangle and between the 
top and bottom coordinates of a horizontal scroll bar’s rectangle. (If you don’t provide a 
16-pixel width, the Control Manager scales the scroll bar to fit the width you specify.) A 
standard scroll bar should be at least 48 pixels long, to allow room for the scroll arrows 
and scroll box. 


The Control Manager draws lines that are 1 pixel wide for the rectangle enclosing the 
scroll bar. As shown in Figure 5-12, the outside lines of a scroll bar should overlap the 
lines that the Window Manager draws for the window frame. 


Figure 5-12 How a scroll bar should overlap the window frame 
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To determine the rectangle for a vertical scroll bar, perform the following calculations and 
use their results in your control resource. (Do not include the area of the title bar in your 
calculations.) 

m top coordinate = combined height of any items above the scroll bar — 1 
m left coordinate = width of window - 15 

m bottom coordinate = height of window - 14 

m right coordinate = width of window + 1 
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To determine the rectangle for a horizontal scroll bar, perform the following calculations 
and use their results in your control resource. 


m top coordinate = height of window — 15 

a left coordinate = combined width of any items to the left of the scroll bar - 1 
m bottom coordinate = height of window + 1 

m right coordinate = width of window — 14 


The top coordinate of a vertical scroll bar is -1, and the left coordinate of a horizontal 
scroll bar is —1, unless your application uses part of the window’s typical scroll bar areas 
(in particular, those areas opposite the size box) for displaying information or specifying 
additional controls. For example, your application may choose to display the current 
page number of a document in the lower-left corner of the window—that is, in a small 
area to the left of its window’s horizontal scroll bar. See Macintosh Human Interface 
Guidelines for a discussion of appropriate uses of a window’s scroll bar areas for 
additional items and controls. 


Just as the maximum settings of a window’s scroll bars change when the user resizes the 
document’s window, so too do the scroll bars’ coordinate locations change when the user 
resizes the window. Although you must specify an initial maximum setting and location 
in the control resource for a scroll bar, your application must be able to change them 
dynamically—typically, by storing handles to each scroll bar in a document record when 
you create a window, and then by using Control Manager routines to change control 
settings (as described in “Determining and Changing Control Settings” beginning on 
page 5-37) and sizes and locations of controls (as described in “Moving and Resizing 
Scroll Bars” beginning on page 5-65). 

Listing 5-4 shows a window resource (described in the chapter “Window Manager” in 
this book) for creating a window, and two control resources for creating the window’s 
vertical and horizontal scroll bars. The rectangle for the initial size and shape of the 
window is specified in global coordinates, of course, and the rectangles for the two scroll 
bars are specified in coordinates local to the window. 


Listing 5-4 Rez input for resources for a window and its scroll bars 


/*initial window*/ 
resource 'WIND' (rDocWindow, preload, purgeable) { 
{64, 60, 314, 460}, /*initial rectangle for window*/ 
zoomDocProc, invisible, goAway, 0x0, "untitled" 
}; 
/*initial vertical scroll bar*/ 
resource 'CNTL' (rVScroll, preload, purgeable) { 
{-1, 385, 236, 401}, /*initial rectangle for control*/ 
/*initial setting, visibility, max, min, ID, refcon, title*/ 
0, invisible, 0, 0, scrollBarProc, 0, "" 
}; 
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/*initial horizontal scroll bar*/ 
resource 'CNTL' (rHScroll, preload, purgeable) { 
{235, -1, 251, 386}, /*initial rectangle for control*/ 
/*initial setting, visibility, max, min, ID, refcon, title*/ 
ww 


0, invisible, 0, 0, scrollBarProc, 0, 
}; 


Listing 5-5 shows an application-defined procedure called DoNew that uses the 
GetNewWindow and GetNewCont rol functions to create a window and its scroll bars 
from the resources in Listing 5-4. 


Listing 5-5 Creating a document window with scroll bars 


PROCEDURE DoNew (newDocument: Boolean; VAR window: WindowPtr) ; 
VAR 





good: Boolean; 
windStorage: Ptr; 
myData: MyDocRecHnd; 
BEGIN 
{use GetNewWindow or GetNewCWindow to create the window here} 
myData := MyDocRecHnd (NewHandle (SIZEOF (MyDocRec))); {create document rec} 


{test for errors along the way; if there are none, create the scroll } 

{ bars and save their handles in myData} 

IF good THEN 

BEGIN {create the vertical scroll bar and save its handle} 
myData**.vScrollBar := GetNewControl(rVScroll, window) ; 
{create the horizontal scroll bar and save its handle} 
myData**.hScrollBar := GetNewControl(rHScroll, window) ; 
good := (vScrollBar <> NIL) AND (hScrollBar <> NIL); 

END; 

IF good THEN 

BEGIN {adjust size, location, settings, and visibility of scroll bars} 
MyAdjustScrollBars (window, FALSE); 





{perform other initialization here} 
IF NOT newDocument THEN 
ShowWindow (window) ; 
END; 
{clean up here} 
END; {DoNew} 


The DoNew routine uses Window Manager routines to create a window; its window 
resource specifies that the window is invisible. The window resource specifies an initial 
size and location for the window, but because the window is invisible, this window is 
not drawn. 
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Then DoNew creates a document record and stores a handle to it in the myData variable. 
The SurfWriter sample application uses this document record to store the data that the 
user creates in this window—as well as handles to the scroll bars that it creates. The 
SurfWriter sample application later uses these control handles to handle scrolling 
through the document and to move and resize the scroll bars when the user resizes the 
window. (See the chapter “Window Manager” in this book for more information about 
creating such a document record.) 


To create scroll bars, DoNew uses Get NewCont rol twice—once for the vertical scroll bar 
and once for the horizontal scroll bar. The Get NewCont rol function returns a control 
handle; DoNew stores these handles in the vScrollBar and hScroll1Bar fields of its 
document record for later reference. 


Because the window and the scroll bars are invisible, nothing is drawn onscreen 

yet for the user. Before drawing the window and its scroll bars, DoNew calls 

another application-defined procedure, MyAdjustScrollBars. In turn, 
MyAdjustScrollBars calls other application-defined routines that move and 

resize the scroll bars to fit the window and then calculate the maximum settings of 

these controls. (Listing 5-14 on page 5-39 shows the MyAdjust ScrollBars procedure.) 





After creating the window and its scroll bars, and then sizing and positioning them 
appropriately, DoNew uses the Window Manager procedure ShowWindow to display the 
window with its scroll bars. 


Creating a Pop-Up Menu 


The values you specify in a control resource for a pop-up menu differ from those you 
specify for other controls. The control resource for a pop-up menu contains the 
following information: 


m arectangle, specified by coordinates local to the window, that determines the size and 
location of the pop-up title and pop-up box 


m the alignment of the pop-up title with the pop-up box 


m aconstant (either visibleorinvisible) that specifies whether the control should 
be drawn on the screen immediately 


a the width of the pop-up title 

m the resource ID of the 'MENU' resource describing the pop-up menu items 
m the control definition ID 

m areference value, which your application may use for any purpose 

m the title of the control 


Figure 5-13 on the next page shows a pop-up menu; Listing 5-6 shows the control 
resource that creates this pop-up menu. (The chapter “Menu Manager” in this book 
recommends typical uses of pop-up menus and describes the relation between pop-up 
menus and menus you display in the menu bar.) 
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Figure 5-13 A pop-up menu 
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Listing 5-6 Rez input for the control resource of a pop-up menu 


resource 'CNTIL' (kPopUpCNTL, preload, purgeable) { 
{90, 18, 109, 198}, /*rectangle of control*/ 
popupTitleLeftJust, /*title position*/ 








visible, /*make control visible*/ 
50, /*pixel width of title*/ 
kPopUpMenu, /*"MENU' resource ID*/ 
popupMenuCDEFProc, /*control definition ID*/ 
0, /*reference value*/ 
"Speed:" /*control title*/ 


hi 


Listing 5-6 specifies a rectangle with the coordinates (90,18,109,198). Figure 5-14 
illustrates the rectangle for this pop-up menu. 


Figure 5-14 Dimensions of a sample pop-up menu 
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Listing 5-6 uses the popupTitleLeftJust constant to specify the position of the 
control title. Specify any combination of the following constants (or their values) to 
inform the Control Manager where and how to draw the pop-up menu’s title: 





Setting Constant Description 

$0000 popupTitleLeftJust Place title left of the pop-up box 
$0001 popupTitleCenterJust Center title over the pop-up box 
$00FF popupTitleRightJust Place title right of the pop-up box 
$0100 popupTitleBold Use boldface font style 

$0200 popupTitlelItalic Use italic font style 
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Setting Constant Description 

$0400 popupTitleUnderline Use underline font style 
$0800 popupTitleOutline Use outline font style 
$1000 popupTitleShadow Use shadow font style 
$2000 popupTitleCondense Use condensed characters 
$4000 popupTitleExtend Use extended characters 
$8000 popupTitleNoStyle Use monostyle font 


If GetNewControl completes successfully, it sets the value of the contr1Value field 
of the control record by assigning to that field the item number of the first menu item. 
When the user chooses a different menu item, the Control Manager changes the 
contrlValue field to that item number. 


When you create pop-up menus, your application should store the handles for them; for 
example, in a record pointed to by the refCon field of a window record or a dialog 
record. (See the chapters “Window Manager” and “Dialog Manager” in this book for 
more information about the window record and the dialog record.) Storing these 
handles, as shown in the following code fragment, allows your application to respond 
later to users’ choices in pop-up menus: 


myData: MyDocRecHnd; 
window: WindowPtr; 


myData**.popUpControlHandle := GetNewControl(kPopUpCNTL, window) ; 


Listing 5-6 specifies 50 pixels (in place of a maximum setting) as the width of the control 
title. After it creates the control, the Control Manager sets the maximum value in the 
pop-up menu’s control record to the number of items in the pop-up menu. Figure 5-14 
illustrates this title width for the pop-up menu. 


Listing 5-6 uses a kPopUpMenu constant to specify the resource ID of a 'MENU' resource 
(in place of a minimum setting for the control). (See the chapter “Menu Manager” in this 
book for a description of the 'MENU' resource type.) After it creates the control, the 

Control Manager assigns 1 as the minimum setting in the pop-up menu’s control record. 


IMPORTANT 

When using the ResEdit application, version 2.1.1, you must use the 
same resource ID when specifying the menu resource and the control 
resource that together define a pop-up menu. A 


You can also specify a different control definition ID by adding any or all of the 
following constants (or the variation codes they represent) to the popupMenuProc 
constant: 





CONST popupFixedWidth = $0001; {use fixed-width control} 
popupUseAddResMenu = $0004; {use resource for menu items} 
popupUseWFont = $0008; {use window font} 
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Constant Description 


popUpFixedWidth Uses a constant control width. If your application specifies 
this value, the pop-up control definition function does not 
resize the control horizontally to fit long menu items. The 
width of the pop-up box is set to the width of the control, 
minus the width of the pop-up title your application 
specifies when it creates the control. If a menu item in a 
pop-up box does not fit in the space provided, the text is 
truncated to fit, and three ellipsis points (...) are appended 
at the end. If you do not specify this variation code, the 
pop-up control definition function may resize the control 
horizontally. 


popupUseAddResMenu Gets menu items from a resource other than the 'MENU' 
resource. If your application specifies this value when 
creating a pop-up menu, the control definition function 
interprets the value in the contr1R£Con field of the 
control record as a value of type ResType. The control 
definition function uses the Menu Manager procedure 
AppendResMenu to add resources of that type to the menu. 


popupUseWFont Uses the font of the specified window. If your application 
specifies this value, the pop-up control definition function 
draws the pop-up menu title using the font and size of 
the window containing the control instead of using the 
system font. 


The reference value that you specify in the control resource (and stored by the Control 
Manager in the cont r1R£Con field of the control record) is available for your 
application’s use. However, if you specify popupUseAddResMenu as a variation code, 
the Control Manager coerces the value in the cont r1R£Con field of the control record 
to the type ResType and then uses AppendResMenu to add items of that type to the 
pop-up menu. For example, if you specify a reference value of LongInt ('FONT') as 
the reference value, the control definition function appends a list of the fonts installed 
in the system to the menu associated with the pop-up menu. After the control has been 
created, your application can use the control record’s contr1RfCon field for whatever 
use it requires. You can determine which menu item is currently chosen by calling 
GetControlValue. 


Whenever the pop-up menu is redrawn, its control definition function calls the Menu 
Manager procedure CalcMenuSize. This procedure recalculates the size of the 

menu associated with the control (to allow for the addition or deletion of items in the 
menu). The pop-up control definition function may also update the width of the pop- 
up menu to the sum of the width of the pop-up title, the width of the longest item in the 
menu, the width of the downward-pointing arrow, and a small amount of white space. 
As previously described, your application can override this behavior by adding the 
variation code popupFixedWidth to the pop-up control definition ID. 

You should not use the Menu Manager function GetMenuHand1e to obtain a handle to 

a menu associated with a pop-up control. If necessary, you can obtain the menu handle 
(and the menu ID) of a pop-up menu by dereferencing the cont r1Data field of the 
pop-up menu’s control record. The cont r1Data field of a control record is a handle to a 
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block of private information. For pop-up menu controls, this field is a handle to a pop-up 
private data record, which is described on page 5-77. 


Updating a Control 


Your program should use the UpdateCont rols procedure upon receiving an update 
event for a window that contains controls such as scroll bars. (Window Manager routines 
such as SelectWindow, ShowWindow, and BringToFront do not automatically 

call UpdateControls to display the window’s controls. Instead, they merely add 

the appropriate regions to the window’s update region. This in turn generates an 

update event.) 





Note 
The Dialog Manager automatically updates the controls you use in alert 
boxes and dialog boxes. # 


When your application receives an update event for a window that contains controls, use 
the UpdateControls procedure in your window-updating code to redraw all the 
controls in the update region of the window. Call UpdateControl1s after using the 
Window Manager procedure BeginUpdate and before using the Window Manager 
procedure EndUpdate. 





When you call UpdateControls, you pass it parameters specifying the window to 
be updated and the window area that needs updating. Use the visible region of 

the window’s graphics port, as referenced in the port’s visRgn field, to specify the 
window’s update region. 


Listing 5-7 shows an application-defined routine, DoUpdate, that responds to an update 
event. The DoUpdate routine calls the Window Manager procedure BeginUpdate. To 
redraw this portion of the window, DoUpdate then calls another of its own procedures, 
MyDrawWindow. 


Listing 5-7 Responding to an update event for a window 





PROCEDURE DoUpdate (window: WindowPtr) ; 
VAR 
windowType: Integer; 
BEGIN 
windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 
BEGIN 
BeginUpdate (window) ; 
MyDrawWindow (window) ; 
EndUpdate (window) ; 

END; {of updating document windows} 
{handle other window types—modeless dialogs, etc.——here} 
END; {of windowType CASE} 

END; {of DoUpdate} 
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Listing 5-8 illustrates how the SurfWriter sample application updates window controls 
and other window contents by using its own application-defined routine, 
MyDrawWindow. To draw only those controls in the window’s update region, 
MyDrawWindow calls UpdateControls. To draw the size box in the lower-right corner 
of the window, MyDrawWindow calls the Window Manager procedure DrawGrowIcon. 
Finally, MyDrawWindow redraws the appropriate information contained in the user’s 
document. Because the SurfWriter application uses TextEdit for all text editing in the 
window contents, Listing 5-8 calls the TextEdit procedure TEUpdate. (TextEdit is 
described in detail in Inside Macintosh: Text.) 


Listing 5-8 Redrawing the controls in the update region 


PROCEDURE MyDrawWindow (window: WindowPtr) ; 

VAR 
myData: MyDocRecHnd; 

BEGIN {draw the contents of the window} 
SetPort (window) ; 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 

HLock (Handle (myData) ); 

WITH window’ DO 

BEGIN 

EraseRect (portRect) ; 











UpdateControls (window, visRgn); 





DrawGrowlIcon (window) ; 
TEUpdate (portRect, myData**.editRec) ; {redraw text} 
END; 
HUnLock (Handle (myData) ); 
END; {MyDrawWindow} 





For more information about updating window contents, see the chapter “Window 
Manager” in this book. 





Responding to Mouse Events in a Control 


The Control Manager provides several routines to help you detect and respond to mouse 
events involving controls. For mouse events in controls, you generally perform the 
following tasks: 


1. In your event-handling code, use the Window Manager function FindWindow to 
determine the window in which the mouse-down event occurred. 


2. If the mouse-down event occurred in the content region of your application’s active 
window, use the FindCont rol function to determine whether the mouse-down 
event occurred in an active control and, if so, which control. 


3. Call TrackCont rol to handle user interaction for the control for as long as the user 
holds the mouse button down. For scroll arrows and the gray areas of scroll bars, you 
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must define an action procedure for TrackCont rol to use. This action procedure 
should cause the document to scroll as long as the user holds down the mouse button. 
For pop-up menus, you pass Pointer (-1) ina parameter to TrackControl to 

use the action procedure defined in the pop-up control definition function. For the 
scroll box in scroll bars and for the other standard controls, you pass NIL ina 
parameter to TrackControl to get the Control Manager’s standard response to 
mouse-down events. 


4. When TrackControl reports that the user has released the mouse button with the 
cursor in a control, respond appropriately. This may require you to use other Control 
Manager routines, such as Get Cont rolValue and SetCont rolValue, to determine 
and change control settings. 


These and other routines for responding to events involving controls are described in the 
next several sections. 


Note 

The Dialog Manager procedure ModalDialog automatically calls 
FindWindow, FindControl, and TrackControl for mouse-down 
events in the controls of alert and modal dialog boxes. You can use the 
Dialog Manager function DialogSelect, which automatically calls 
FindWindow, FindControl, and TrackControl, to help you handle 
mouse events in your movable modal and modeless dialog boxes. 


Determining a Mouse-Down Event in a Control 


When your application receives a mouse-down event, use the Window Manager 
function F indWindow to determine the window in which the event occurred. If the 
cursor was in the content region of your application’s active window when the user 
pressed the mouse button, use the FindControl function to determine whether the 
mouse-down event occurred in an active control and, if so, which control. 


When the mouse-down event occurs in a visible, active control, FindControl returns a 
handle to that control as well as a part code identifying the control’s part. (Note that 
when the mouse-down event occurs in an invisible or inactive control, or when the 
cursor is not in a control, FindControl sets the control handle to NIL and returns 0 as 
its part code.) 


A simple control such as a button or checkbox might have just one “part”; a more 
complex control can have as many parts as are needed to define how the control 
operates. A scroll bar has five parts: two scroll arrows, the scroll box, and the two gray 
areas on either side of the scroll box. Figure 5-4 on page 5-7 shows the five parts of a 
scroll bar. 


A part code is an integer from 1 through 253 that identifies a part of a control. To allow 
different parts of a multipart control to respond to mouse events in different ways, many 
of the Control Manager routines accept a part code as a parameter or return one as 

a result. Part codes are assigned to a control by its control definition function. The 
standard control definition functions define the following part codes. Also listed are the 
constants you can use to represent them. 
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Constant Part code Conirol part 

inButton 10 Button 

inCheckBox 11 Entire checkbox or radio button 

inUpButton 20 Up scroll arrow for a vertical scroll bar, left scroll 
arrow for a horizontal scroll bar 

inDownButton 21 Down scroll arrow for a vertical scroll bar, right 
scroll arrow for a horizontal scroll bar 

inPageUp 22 Gray area above scroll box for a vertical scroll 
bar, gray area to left of scroll box for a horizontal 
scroll bar 

inPageDown 23 Gray area below scroll box for a vertical scroll bar, 
gray area to right of scroll box for a horizontal 
scroll bar 

inThumb 129 Scroll box 


The pop-up control definition function does not define part codes for pop-up menus. 
Instead (as explained in “Creating a Pop-Up Menu” beginning on page 5-25), your 
application should store the handles for your pop-up menus when you create them. 
Your application should then test the handles you store against the handles returned 
by FindCont rol before responding to users’ choices in pop-up menus; this is described 
in more detail later in the next section. 


Listing 5-9 illustrates an application-defined procedure, DoMouseDown, that an 
application might call in response to a mouse-down event. The DoMouseDown routine 
first calls the Window Manager function FindWindow, which returns two values: a 
pointer to the window in which the mouse-down event occurred and a constant that 
provides additional information about the location of that event. If FindWindowreturns 
the inContent constant, then the mouse-down event occurred in the content area of 

one of the application’s windows. 


Listing 5-9 Detecting mouse-down events in a window 


PROCEDURE DoMouseDown (event: EventRecord) ; 
VAR 

part: Integer; 

thisWindow: WindowPtr; 
BEGIN {handle mouse-down event } 





part := FindWindow(event.where, thisWindow) ; 
CASE part OF 


inMenuBar: 





y {mouse-down in menu bar, respond appropriately here} 
inContent: 
IF thisWindow <> FrontWindow THEN 
{mouse-down in an inactive window; use SelectWindow } 


{ to make it active here} 
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ELSE {mouse-down in the active window} 








DoContentClick (thisWindow, event); 
{handle other cases here} 
END; {of CASE statement } 
END; { DoMouseDown } 





In Listing 5-9, when FindWindow reports a mouse-down event in the content region of a 
window containing controls, DoMouseDown calls another application-defined procedure, 
DoContentClick, and passes it the window pointer returned by the FindWindow 
function as well as the event record. 


Listing 5-10 shows an application-defined procedure, DoContentClick, that uses this 
information to determine whether the mouse-down event occurred in a control. 


Listing 5-10 Detecting mouse-down events in a pop-up menu and a button 


PROCEDURE DoContentClick (window: WindowPtr; event: EventRecord) ; 
VAR 


mouse: Point; 
control: ControlHandle; 
part: Integer; 
windowType: Integer; 
BEGIN 
windowType := MyGetWindowType (window) ; {get window type} 


CASE windowType OF 


kPlaySoundsModelessDialogBox: 
BEGIN 
SetPort (window) ; 





mouse := event.where; {get the mouse location} 
GlobalToLocal (mouse) ; {convert to local coordinates} 
part := FindControl(mouse, window, control); 


IF control = gSpeedPopUpControlHandle THEN 
{mouse-down in Modem Speed pop-up menu} 
DoPopUpMenu (mouse, control); 

CASE part OF 
inButton: {mouse-down in Play button} 

DoPlayButton(mouse, control); 
inCheckBox: {mouse-down in checkbox} 
DoDrumRollCheckBox (mouse, control); 
OTHERWISE 
i 


END; {of CASE for control part codes} 
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END; {of kPlaySoundsModelessDialogBox case} 
{handle other window types, such as document windows, here} 
END; {of CASE for window types} 

END; {of DoContentClick} 


Figure 5-15 shows the Play Sounds window; DoContentClick uses the FindControl 
function to determine whether the mouse-down event occurred in the pop-up menu, the 
Play button, or the Add Drum Roll checkbox. 


First, however, DoContentClick uses the event record to determine the cursor 
location, which is specified in global coordinates. Because the FindCont rol function 
expects the cursor location in coordinates local to the window, DoContentClick uses 
the QuickDraw procedure GlobalToLocal to convert the point stored in the where 
field of the event record to coordinates local to the current window. The 
GlobalToLocal procedure takes one parameter, a point in global coordinates—where 
the upper-left corner of the entire bit image is coordinate (0,0). See Inside Macintosh: 
Imaging for more information about the Global ToLocal procedure. 


Figure 5-15 Three controls in a window 
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When it calls FindControl, DoContentClick passes the cursor location in the 
window’s local coordinates as well as the pointer returned earlier by the FindWindow 
function (shown in Listing 5-9 on page 5-32). 


If the cursor is in a control, FindControl returns a handle to the control and a part 
code indicating the control part. Because the pop-up control definition function does 
not define control parts, DoContentClick tests the control handle returned by 
FindControl against a pop-up menu’s control handle that the application stores 

in its own global variable. If these are handles to the same control, DoContentClick 
calls another application-defined routine, DoPopUpMenu. 


After checking whether FindControl returns a control handle to a pop-up menu, 
DoContentClick uses the part code that FindCont rol returns to determine whether 
the cursor is in one of the other two controls. If FindControl returns the inButton 
constant, DoContentClick calls another application-defined routine, DoPlayButton. 
If FindControl returns the inCheckBox constant, DoContentClick calls another 
application-defined routine, DoDrumRol1lCheckBox. 
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As described in the next section, all three of these application-defined routines— 
DoPopUpMenu, DoPlayButton, and DoDrumRo11CheckBox—in turn use the 
TrackControl function to follow and respond to the user’s mouse movements in 
the control reported by FindControl. 





Tracking the Cursor in a Control 


After using the FindCont rol function to determine that the user pressed the mouse 
button when the cursor was in a control, use the TrackCont rol function first to follow 
and respond to the user’s mouse movements, and then to determine which control part 
contains the cursor when the user releases the mouse button. 


Generally, you use TrackCont rol after using the FindControl function to determine 
that the mouse-down event occurred in a control. You pass to TrackCont rol the 
control handle returned by the FindCont rol function, and you also pass to 
TrackControl the same point you passed toFindControl (that is, a point in 
coordinates local to the window). 


The TrackControl function follows the movements of the cursor in a control and 
provides visual feedback until the user releases the mouse button. The visual feedback 
given by TrackCont rol depends on the control part in which the mouse-down event 
occurred. When highlighting the control is appropriate—in a button, for example— 
TrackControl highlights the control part (and removes the highlighting when the user 
releases the mouse button). When the user presses the mouse button while the cursor is 
in an indicator (such as the scroll box of a scroll bar) and then moves the mouse, 
TrackControl responds by dragging a dotted outline of the indicator. Figure 5-8 on 
page 5-12 illustrates how TrackControl provides visual feedback. 


You can also use an action procedure to undertake additional actions as long as the user 
holds down the mouse button. For example, if the user is working in a text document 
and holds down the mouse button while the cursor is in a scroll arrow, your action 
procedure should continuously scroll through the document one line (or some 
equivalent measure) at a time until the user releases the button or reaches the end of the 
document. You pass a pointer to this procedure to TrackCont rol. (“Scrolling in 
Response to Events in Scroll Arrows and Gray Areas” beginning on page 5-57 describes 
how to do this.) 


The TrackControl function returns the control’s part code if the user releases 

the mouse button while the cursor is inside the control part, or 0 if the user releases the 
mouse button while the cursor is outside the control part. Unless TrackControl 
returns 0 as its function result, your application should then respond as appropriate to 
a mouse-up event in that control part. When TrackCont rol returns 0 as its function 
result, your application should do nothing. 





Listing 5-11 on the next page shows an application-defined procedure, DoPlayButton, 
that uses TrackCont rol to track mouse-down events in the Play button shown in 
Figure 5-15. The DoPlayButton routine passes, to TrackCont rol, the control handle 
returned by FindControl. The DoPlayButton routine also passes to TrackControl 
the same cursor location it passed to FindCont rol (that is, a point in local coordinates). 
Because buttons don’t need an action procedure, NIL is passed as the final parameter 

to TrackControl. 
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Listing 5-11 Using the TrackControl function with a button 


PROCEDURE DoPlayButton (mouse: Point; control: ControlHandle) ; 


IF TrackControl(control, mouse, NIL) <> 0 THEN {user clicks Play} 


BEGIN 
IF gPlayDrumRoll = TRUE THEN {user clicked Play Drum Roll checkbox } 
DoPlayDrumRoll; { so play a drum roll first} 


END; 
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SysBeep (30) ; {always play system alert sound when user clicks Play} 
END; 


When the user presses the mouse button when the cursor is in the Play button, 
TrackControl inverts the Play button. If the user releases the mouse button after 
moving the cursor outside the control part, TrackCont rol stops inverting the 
button and returns the value 0, in which case DoP layButton does nothing. 


If, however, the user releases the mouse button with the cursor in the Play button, 
TrackControl stops inverting the Play button and returns the value for the inButton 
constant. Then DoPlayButton calls the Sound Manager procedure SysBeep to play the 
system alert sound (which is described in the chapter “Dialog Manager” in this book). 
Before releasing the mouse button, the user can move the cursor away from the control 
part and then return to it, and TrackContro1 will still return the part code when the 
user releases the mouse button. 


For buttons, checkboxes, radio buttons, and the scroll box in a scroll bar, your application 
typically passes NIL to TrackControl to use no action procedure. However, 
TrackControl still responds visually to mouse events in active controls. That is, when 
the user presses the mouse button with the cursor over a control whose action procedure 
is set to NIL, TrackControl changes the control’s display appropriately until the user 
releases the mouse button. 


For scroll arrows and for the gray areas of a scroll box, you need to define your own 
action procedures. You pass a pointer to the action procedure as one of the parameters to 
TrackControl, as described in “Scrolling in Response to Events in Scroll Arrows and 
Gray Areas” beginning on page 5-57. 


For a pop-up menu, you must pass Pointer (-1) toTrackControl for its action 
procedure; this causes TrackCont rol to use the action procedure defined in the pop-up 
control definition function. 


Listing 5-10 on page 5-33 calls an application-defined routine, DoPopUpMenu, when 
FindControl reports a mouse-down event in a pop-up menu. Listing 5-12 shows how 
DoPopUpMenu uses TrackCont rol to handle user interaction in the pop-up menu. By 
passing Pointer (-1) to TrackControl, DoPopUpMenu uses the action procedure 
defined in the pop-up control definition function. 
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Listing 5-12 Using TrackControl with a pop-up menu 


PROCEDURE DoPopUpMenu (mouse: Point; control: ControlHandle) ; 
VAR 














menulItem: Integer; 
part: Integer; 
BEGIN 
part := TrackControl(control, mouse, Pointer(-1)); 
menulItem := GetControlValue (control); 
IF menuitem <> gCurrentItem THEN 
BEGIN 
gCurrentItem := menulItem; 


SetMyCommunicationSpeed; {use speed stored in gCurrentItem} 
END; 
END; {of DoPopUpMenu} 


The action procedure for pop-up menus highlights the pop-up menu title, displays the 
pop-up menu, and handles all user interaction while the user drags up and down the 
menu. When the user releases the mouse button, the action procedure closes the pop-up 
box, draws the user’s choice in the pop-up box (or restores the previous item if the user 
doesn’t make a new choice), and removes the highlighting of the pop-up title. The 
pop-up control definition function then changes the value of the contr1Value field of 
the control record to the number of the menu item chosen by the user. 


Because buttons do not retain settings, responding to them is very straightforward: when 
the user clicks a button, your application should immediately undertake the action 
described by the button’s title. For pop-up menus and other types of controls, you must 
determine their current settings before responding to the user’s action. For example, 
before responding, you need to know which item the user has chosen in a pop-up menu, 
whether a checkbox is checked, or how far the user has moved the scroll box. The action 
you take may, in turn, involve changing other control settings. Determining and 
changing control settings are described in the next section. 


After learning how to determine and change control settings, see “Scrolling Through a 
Document” beginning on page 5-43 for a detailed discussion of how to respond to mouse 
events in scroll bars. 


Determining and Changing Control Settings 


Using either the control resource or the parameters to the NewCont rol function, your 
application specifies a control’s various default values—such as its current setting and 
minimum and maximum settings—when it creates the control. 


When the user clicks a control, however, your application often needs to determine 

the current setting and other possible values of that control. When the user clicks a 
checkbox, for example, your application must determine whether the box is checked 
before your application can decide whether to clear or draw a checkmark inside the 
checkbox. When the user moves the scroll box, your application needs to determine what 
part of the document to display. 
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Applications must adjust some controls in response to events other than mouse events in 
the controls themselves. For example, when the user resizes a window, your application 
must use the Control Manager procedures MoveCont rol and SizeCont rol to move 
and resize the scroll bars appropriately. 


Your application can use the Get Cont rolValue function to determine the current 
setting of a control, and it can use the Get Cont rolMaximum function to determine a 
control’s maximum setting. 


You can use the Set Cont rolValue procedure to change the control’s setting and 
redraw the control accordingly. You can use the Set Cont rolMaximum procedure to 
change a control’s maximum setting and to redraw the indicator or scroll box to reflect 
the new setting. 


In response to user action involving a control, your application often needs to change the 
setting and possibly redraw the control. When the user clicks a checkbox, for example, 
your application must determine whether the checkbox is currently selected or not, and 
then switch its setting. When you use Set Cont rolValue to switch a checkbox setting, 
the Control Manager either draws or removes the X inside the checkbox, as appropriate. 
When the user clicks a radio button, your application must determine whether the radio 
button is already on and, if not, turn the previously selected radio button off and turn 
the newly selected radio button on. 


Figure 5-15 on page 5-34 shows a checkbox in the Play Sounds window. When the user 
clicks the checkbox to turn it on, the application adds a drum roll to the sound it plays 
whenever the user clicks the Play button. 


Listing 5-13 shows the application-defined routine DoDrumRol1lCheckBox, which 
responds to a click in a checkbox. This routine uses the Get Cont rolValue function to 
determine the last value of the checkbox and then uses the SetControlValue 
procedure to change it. The Get Cont rolValue function returns a control’s current 
setting, which is stored in the contr1Value field of the control record. The 
SetControlValue procedure sets the contr1Value field to the specified value and 
redraws the control to reflect the new setting. (For checkboxes and radio buttons, the 
value 1 fills the control with the appropriate mark, and the value 0 removes the mark. 
For scroll bars, Set Cont rolValue redraws the scroll box at the appropriate position 
along the scroll bar. For a pop-up menu, Set Cont rolValue displays in its pop-up box 
the name of the menu item corresponding to the specified value.) 


Listing 5-13 Responding to a click in a checkbox 


PROCEDURE DoDrumRollCheckBox (mouse: Point; control: ControlHandle)j; 








VAR 
checkbox: Integer; 
BEGIN 
IF TrackControl(control, mouse, NIL) <> 0 THEN {user clicks checkbox} 
BEGIN 
checkbox := GetControlValue (control); {get last value of checkbox} 
checkbox := 1 - checkbox; {toggle value of checkbox} 
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SetControlValue (control, checkbox) ; {set checkbox to new value} 
IF checkbox = 1 THEN {the checkbox is checked} 
gPlayDrumRoll := TRUE {play a drum roll next time user clicks Play} 
ELSE 
gPlayDrumRoll := FALSE; 
END; 





The DoDrumRol1CheckBox routine uses TrackCont rol to determine which control 
the user selects. When TrackControl reports that the user clicks the checkbox, 
DoDrumRol1lCheckBox uses Get Cont rolValue to determine whether the user last 
selected the checkbox (that is, whether the control has a current setting of 1) or 
deselected it (in which case, the control has a current setting of 0). By subtracting the 
control's current setting from 1, DoDrumRol1CheckBox toggles to a new setting 

and then uses Set Cont rolValue to assign this new setting to the checkbox. The 
SetControlValue procedure changes the current setting of the checkbox and redraws 
it appropriately, by either drawing an X in the box if the new setting of the control is 1 or 
removing the X if the new setting of the control is 0. 


Listing 5-4 on page 5-23 shows the control resources that specify a window’s scroll bars, 
and Listing 5-5 on page 5-24 shows an application’s DoNew routine for creating a 
document window with these scroll bars. This routine uses the GetNewCont rol 
function to create the scroll bars and then calls an application-defined routine, 
MyAdjustScrollBars. Listing 5-14 shows MyAdjustScrollBars, which in turn 
calls other application-defined routines that determine the proper sizes, locations, 

and maximum settings of the scroll bars. 


Listing 5-14 Adjusting scroll bar settings and locations 





PROCEDURE MyAdjustScrollBars (window: WindowPtr; 
resizeScrollBars: Boolean) ; 











VAR 
myData: MyDocRecHnd; 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 


HLock (Handle (myData) ); 
WITH myData** DO 





BEGIN 
HideControl (vScrollBar) ; {hide the vertical scroll bar} 
HideControl (hScrollBar) ; {hide the horizontal scroll bar} 
IF resizeScrollBars THEN {move and size if needed} 





MyAdjustScrollSizes (window) ; 





MyAdjustScrollValues (window, NOT resizeScrollBars) ; 


ShowControl (vScrollBar) ; {show the vertical scroll bar} 
ShowControl (hScrollBar) ; {show the horizontal scroll bar} 
END; 


HUnLock (Handle (myData) ); 
END; {of MyAdjustScrollbars} 
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When calling the DoOpen routine to open an existing document in a window, 
SurfWriter also uses this MyAdjustScrollBars procedure to size and adjust the 
scroll bars. When the user changes the window’s size, the SurfWriter application 
uses MyAdjustScrollBars again. 





The MyAdjustScrollBars routine begins by getting a handle to the window’s 
document record, which stores handles to the scroll bars as well as other relevant data 
about the document. (See the chapter “Window Manager” in this book for information 
about creating your application’s own document record for a window.) 


Before making any adjustments to the scroll bars, MyAdjust Scroll1Bars passes the 
handles to these controls to the Control Manager procedure HideCont rol, which 
makes the controls invisible. The MyAdjustScrollBars routine then calls another 
application-defined procedure, MyAdjustScrollSizes (shown in Listing 5-24 on 
page 5-67), to move and resize the scroll bars appropriately. After calling yet another 
application-defined procedure, MyAdjustScrollValues, to set appropriate current 
and maximum settings for the scroll bars, MyAdjustScrollBars uses the Control 
Manager procedure ShowCont rol to display the scroll bars in their new locations. 





Listing 5-15 shows how the MyAdjustScroll1Values procedure calls another 
application-defined routine, MyAdjustHV, which uses Control Manager routines to 
assign appropriate settings to the scroll bars. 


Listing 5-15 Assigning settings to scroll bars 





PROCEDURE MyAdjustScrollValues (window: WindowPtr) ; 
VAR 
myData: MyDocRecHnd; 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
WITH myData** DO 
BEGIN 
MyAdjustHV(TRUE, vScrollBar, editRec); 
MyAdjustHV(FALSE, hScrollBar, editRec); 
END; 
HUnLock (Handle (myData) ); 
END; {of MyAdjustScrollValues} 








To prevent the user from scrolling past the edge of the document and seeing a blank 
window, you should limit the scroll bars’ maximum settings, as illustrated in Figure 5-6 
on page 5-10. If the window is larger than the document (which can easily happen with 
small documents on large monitors), your application should make the maximum scroll 
bar settings identical to their minimum settings. In this case, the Control Manager then 
makes the scroll bars inactive, which is appropriate when all the information fits in 

the window. 
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Listing 5-16 shows the application-defined MyAdjustHV procedure, used for adjusting 
the current and maximum settings for a scroll bar. When passed TRUE in the isVert 
parameter, MyAdjustHV calculates and adjusts the maximum and current settings for 
the vertical scroll bar; when passed FALSE, it calculates and adjusts those settings for the 
horizontal scroll bar. 








In this example, the document consists of monostyled text stored in a TextEdit edit 
record. The viewRect field of a TextEdit edit record specifies the rectangle where the 
text is visible; because viewRect already excludes the scroll bar regions, MyAdjustHV 
does not need to subtract the scroll bar regions from the window height or width when 
calculating the maximum settings for these scroll bars. (For more information about 
TextEdit in general and the edit record in particular, see Inside Macintosh: Text.) 


Listing 5-16 Adjusting the maximum and current settings for a scroll bar 





PROCEDURE MyAdjustHV (isVert: Boolean; control: ControlHandle; 
editRec: TEHandle) ; 


VAR 
oldValue, oldMax, width: Integer; 
max, lines, value: Integer; 
BEGIN 


{calculate new maximum and current settings for the vertical or } 
{ horizontal scroll bar} 


oldMax := GetControlMaximum(control); 
oldValue := GetControlValue (control); 
MyGetDocWidth (width) ; 
IF isVert THEN {adjust max setting for the vertical scroll bar} 
BEGIN 
lines := editRec**’%.nLines; 


{since nLines isn't right if the last character is a carriage } 
{ return, check for that case} 
IF Ptr (ORD (editRec**.hText*) + editRec**%.teLength - 1)* = kCRChar THEN 





lines := lines + 1; 


lines —- ((editRec**.viewRect.bottom - editRec**.viewRect.top) 
DIV editRec**%.lineHeight) ; 


max 





END 
ELSE {adjust max setting for the horizontal scroll bar} 

max := width - (editRec**.viewRect.right - editRec**.viewRect.left); 
IF max < 0 THEN 

max := 0; {check for negative settings} 


SetControlMaximum(control, max); {set the max value of the control} 
IF isVert THEN {adjust current setting for vertical scroll bar} 
value := (editRec**.viewRect.top - editRec**.destRect.top) 
DIV editRec*’*’%.lineHeight 
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{adjust current setting for the horizontal scroll bar} 
:= editRec**.viewRect.left - editRec**.destRect.left; 





IF value < 0 THEN 


value 





:= 0 


ELSE IF value > max THEN 


value 





:= max; {don't allow current setting to be greater than the } 


{ maximum setting} 


SetControlValue(control, value); 
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END; {of MyAdjustHV} 


The MyAdjustHV routine first uses the Get Cont rolMaximum and GetControlValue 
functions to determine the maximum and current settings for the scroll bar 
being adjusted. 


Then MyAdjustHV calculates a new maximum setting for the case of a vertical scroll bar. 
Because the window displays a text-only document, MyAdjustHV uses thenLines field 
of the edit record to determine the total number of lines in—and hence, the length of— 
the document. Then MyAdjust HV subtracts the calculated height of the window from 
the length of the document, and makes this value the maximum setting for the vertical 
scroll bar. 


To calculate the total height in pixels of the window, MyAdjust HV begins by subtracting 
the top coordinate of the view rectangle from its bottom coordinate. (The upper-left 
corner of a window is normally at point [0,0]; therefore the vertical coordinate of a 

point at the bottom of a rectangle has a larger value than a point at the top of the 
rectangle.) Then MyAdjustHV divides the pixel height of the window by the value of 
the edit record’s lineHeight field, which for monostyled text specifies the document's 
line height in pixels. By dividing the window height by the line height of the text, 
MyAdjustHV determines the window’s height in terms of lines of text. 


The MyAdjust HV routine uses another application-defined routine, MyGetDocWidth, 
to determine the width of the document. To calculate the width of the window, 
MyAdjustHV subtracts the left coordinate of the view rectangle from its right coordinate. 
By subtracting the window width from the document width, MyAdjustHV derives the 
maximum setting for the horizontal scroll bar. 


For both vertical and horizontal scroll bars, MyAdjustHV assigns a maximum setting of 
0 whenever the window is larger than the document—for instance, when a window is 
created for a new document that contains no data yet. In this case, MyAdjust HV assigns 
the same value, 0, to both the maximum and current settings for the scroll bar. The 
standard control definition function for scroll bars automatically makes a scroll bar 
inactive when its minimum and maximum settings are identical. This is entirely 
appropriate, because whenever the user has nowhere to scroll, the scroll bar should be 
inactive. When you make the maximum setting exceed the minimum, the control 
definition function makes the scroll bar active again. 


The MyAdjustHV routine then uses the Control Manager procedure 
SetControlMaximum to assign the newly calculated maximum settings to either 
scroll bar. The Set Cont rolMaximum procedure revises the control to reflect the new 
maximum setting; for example, if the user deletes a large portion of the document, 
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thereby reducing the maximum setting, Set Cont rolMaximum moves the scroll box 
to indicate the new position relative to the smaller document. 


When the user adds information to or removes information from a document or adjusts 
its window size, your application may need to adjust the current setting of the scroll bar 
as well. The MyAdjustHV routine calculates a new current setting for the control and 
then uses Set Cont rolValue to assign that setting to the control as well as to reposition 
the scroll box accordingly. 


The destination rectangle, specified in the destRect field of the edit record, is the 
rectangle in which the text is drawn, whereas the view rectangle is the rectangle in which 
the text is actually visible. By subtracting the top coordinate of the destination rectangle 
from the top coordinate of the view rectangle, and dividing the result by the line height, 
MyAdjustHV derives the number of the line currently displayed at the top of the 
window. This is the line number MyAdjustHV uses for the current setting of the vertical 
scroll bar. 


To derive the current setting of the horizontal scroll bar in terms of pixels, MyAdjust HV 
subtracts the left coordinate of the destination rectangle from the left coordinate of the 
view rectangle. 


Scrolling Through a Document 


Earlier sections of this chapter explain how to create scroll bars, determine when a 
mouse-down event occurs in a scroll bar, track user actions in a scroll bar, and determine 
and change scroll bar settings. This section discusses how your application actually 
scrolls through documents in response to users’ mouse activity in the scroll bars. For 
example, your application scrolls toward the bottom of the document under the 
following conditions: 


m When the user drags the scroll box to the bottom of the vertical scroll bar, your 
application should display the end of the user’s document. 

m When the user clicks the gray area below the scroll box, your application should move 
the document up to display the next window of information toward the bottom of the 
document, and it should use Set Cont rolValue to move the scroll box. 


mg When the user clicks the down scroll arrow, your application should move the 
document up by one line (or by some similar measure) and bring more of the bottom 
of the document into view, and it should use Set Cont rolValue to move the 
scroll box. 
As a first step, your application must determine the distance by which to scroll. When 
the user drags a scroll box to a new location on the scroll bar, you scroll a corresponding 
distance to a new location in the document. 


When the user clicks a scroll arrow, your application determines an appropriate amount 
to scroll. In general, a word processor scrolls vertically by one line of text and horizon- 
tally by the average character width, and a database or spreadsheet scrolls by one field. 
Graphics applications should scroll to display an entire object when possible. (Typically, 
applications convert these distances to pixels when using Control Manager, QuickDraw, 
and TextEdit routines.) 
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When the user clicks a gray area of a scroll bar, your application should scroll by a 
distance of just less than the height or width of the window. To determine this height 
and width, you can use the cont r1lOwner field of the scroll bar’s control record. This 
field contains a pointer to the window record. When you scroll by a distance of one 
window, it is best to retain part of the previous window. This retained portion helps the 
user place the material in context. For example, if the user scrolls down by a distance of 
one window in a text document, the line at the top of the window should be the one that 
previously appeared at the bottom of the window. 


The scrolling direction is determined by whether the scrolling distance is expressed as a 
positive or negative number. When the user scrolls down or to the right, the scrolling 
distance is a negative number; when the user scrolls up or to the left, the scrolling 
distance is a positive number. For example, when the user scrolls from the beginning of a 
document to a line located 200 pixels down, the scrolling distance is —200 pixels on the 
vertical scroll bar. When the user scrolls from there back to the start of the document, the 
scrolling distance is 200 pixels. 


Determining the scrolling distance is only the first step. In brief, your application should 
take the following steps to scroll through a document in response to the user’s 
manipulation of a scroll bar. 


1. Use the FindControl, GetControlValue, and TrackControl functions to help 
calculate the scrolling distance. 


2. If you are scrolling for any reason other than the user dragging the scroll box, use the 
SetControlValue procedure to move the scroll box a corresponding amount. 


3. Use a routine—such as the QuickDraw procedure ScrollRect or the TextEdit 
procedure TEP inScrol1—to move the bits displayed in the window by the 
calculated scrolling distance. Then either use a call that generates an update event 
or else directly call your application’s DoUpdate routine, which should perform 
the rest of these steps. 





4. Use the UpdateControls procedure to update the scroll bars and then call the 
Window Manager procedure DrawGrowIcon to redraw the size box. 


5. Use the QuickDraw procedure Set Origin to change the window origin by an 
amount equal to the scroll bar settings so that the upper-left corner of the document 
lies at (0,0) in the window’s local coordinate system. (You perform this step so that 
your application’s document-drawing routines can draw in the correct area of the 
window.) 


6. Call your application’s routines for redrawing the document inside the window. 


7. Use the SetOrigin procedure to reset the window origin to (0,0) so that future 
Window Manager and Control Manager routines draw in the correct area of the 
window. 


8. Return to your event loop. 


These steps are explained in greater detail in the rest of this section. 
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Note 

It is not necessary to use Set Origin as described in the rest of this 
chapter. This procedure merely helps you to offset the window origin 
by the scroll bars’ current settings when you update the window, so 
that you can locate objects in a document using a coordinate system 
where the upper-left corner of the document is always at (0,0). As an 
alternative to this approach, your application can leave the upper-left 
corner of the window (called the window origin) located at (0,0) and 
instead offset the items in your document by an amount equal to the 
scroll bars’ settings. The QuickDraw procedures Of fsetRect, 
OffsetRgn, SubPt, and AddPt, which are described in Inside 
Macintosh: Imaging, are useful if you pursue this alternate approach. 


When the user saves a document, your application should store the data in your own 
application-defined data structures. (For example, the sample code in this chapter 
stores a handle to a TextEdit edit record in a document record. The edit record contains 
information about the text, such as it length and its own local coordinate system, and 
a handle to the text itself.) You typically store information about the objects your 
application displays onscreen by using coordinates local to the document, where the 
upper-left corner of the document is located at (0,0). 


The left side of Figure 5-16 on the next page illustrates a case in which the user has just 
opened an existing document, and the SurfWriter sample application displays the top of 
the document. In this example, the document consists of 35 lines of monostyled text, and 
the line height throughout is 10 pixels. Therefore, the document is 350 pixels long. When 
the user first opens the document, the window origin is identical to the upper-left point 
of the document’s space: both are at (0,0). 


In this example, the window displays 15 lines of text, which amount to 150 pixels. 
Hence, the maximum setting for the scroll bar is 200 because the vertical scroll bar’s 
maximum setting is the length of the document minus the height of its window. 


Imagine that the user drags the scroll box halfway down the vertical scroll bar. Because 
the user wishes to scroll down, the SurfWriter application must move the text of the 
document up so that more of the bottom of the document shows. Moving a document up 
in response to a user request to scroll down requires a scrolling distance with a negative 
value. (Likewise, moving a document down in response to a user request to scroll up 
requires a scrolling distance with a positive value.) 


Using FindControl, TrackControl, and GetControlValue, the SurfWriter 
application determines that it must move the document up by 100 pixels—that is, 
by a scrolling distance of -100 pixels. (Using FindControl, TrackControl, and 
GetControlValue to determine the scrolling distance is explained in detail in 
“Scrolling in Response to Events in the Scroll Box” beginning on page 5-53.) 
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Figure 5-16 Moving a document relative to its window 
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The SurfWriter application then uses the QuickDraw procedure Scrol1Rect to shift 
the bits displayed in the window by a distance of —100 pixels. The Scrol1lRect 
procedure moves the document upward by 100 pixels (that is, by 10 lines); 5 lines from 
the bottom of the previous window display now appear at the top of the window, 

and the SurfWriter application adds the rest of the window to an update region for 
later updating. 


The ScrollRect procedure doesn’t change the coordinate system of the window; 
instead it moves the bits in the window to new coordinates that are still in the window’s 
local coordinate system. For purposes of updating the window, you can think of this 

as changing the coordinates of the entire document, as illustrated in the right side of 
Figure 5-16. 


The ScrollRect procedure takes four parameters: a rectangle to scroll, a horizontal 
distance to scroll, a vertical distance to scroll, and a region handle. Typically, when 
specifying the rectangle to scroll, your application passes a value representing the 
content region minus the scroll bar regions, as shown in Listing 5-17. 
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Listing 5-17 Using ScrollRect to scroll the bits displayed in the window 





PROCEDURE DoGraphicsScroll (window: WindowPtr; 
hDistance, vDistance: Integer); 
VAR 
myScrollRect: Rect; 
updateRegion: RgnHandle; 
BEGIN 
{initially, use the window's portRect as the rectangle to scroll} 
myScrollRect := window’.portRect; 
{subtract vertical and horizontal scroll bars from rectangle} 


myScrollRect.right := myScrollRect.right - 15; 
myScrollRect.bottom := myScrollRect.bottom - 15; 
updateRegion := NewRgn; {always initialize the update region} 


ScrollRect (myScrollRect, hDistance, vDistance, updateRegion) ; 
InvalRgn (updateRegion) ; 
DisposeRgn (updateRegion) ; 

END; {of DoGraphicsScroll} 


IMPORTANT 

You must first pass a horizontal distance as a parameter to Scrol1lRect 
and then pass a vertical distance. Notice that when you specify a point 
in the QuickDraw coordinate system, the opposite is true: you name the 
vertical coordinate first and the horizontal coordinate second. A 


Although each scroll bar is 16 pixels along its shorter dimension, the 
DoGraphicsScrol1 procedure shown in Listing 5-17 subtracts only 15 pixels 
because the edge of the scroll bar overlaps the edge of the window frame, leaving 
only 15 pixels of the scroll bar in the content region of the window. 


The bits that ScrollRect shifts outside of the rectangle specified by myScrollRect 
are not drawn on the screen, and they are not saved—it is your application’s 
responsibility to keep track of this data. 


The ScrollRect procedure shifts the bits a distance of hDistance pixels horizontally 
and vDistance pixels vertically; when DoGraphicsScro11 passes positive values in 
these parameters, ScrollRect shifts the bits in the myScrollRect parameter to the 
right and down, respectively. This is appropriate when the user intends to scroll left or 
up, because when the SurfWriter application finishes updating the window, the user sees 
more of the left and top of the document, respectively. (Remember: to scroll up or left, 
move the document down or right, both of which are in the positive direction.) 


When DoGraphicsScrol1 passes negative values in these parameters, ScrollRect 
shifts the bits in the myScrol1Rect parameter to the left or up. This is appropriate 
when the user intends to scroll right or down, because when the SurfWriter application 
finishes updating the window, the user sees more of the right and the bottom of the 
document. (Remember: to scroll down or right, move the document up or left, both of 
which are in the negative direction.) 
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In Figure 5-16, the SurfWriter application determines a vertical scrolling distance of -100, 
which it passes in the vDistance parameter as shown here: 


ScrollRect (myScrollRect, 0, -100, updateRegion) ; 


If, however, the user were to move the scroll box back to the beginning of the document 
at this point, the SurfWriter application would determine that it has a distance of 

100 pixels to scroll up, and it would therefore pass a positive value of 100 in the 
vDistance parameter. 


After using ScrollRect to move the bits that already exist in the window, the 
SurfWriter application should draw the bits in the update region of the window by using 
its standard window-updating code. 


As previously explained, Scrol1Rect in effect changes the coordinates of the document 
relative to the local coordinates of the window. In terms of the window’s local coordinate 
system, the upper-left corner of the document is now at (—100, 0), as shown on the right 
side of Figure 5-16. To facilitate updating the window, the SurfWriter application uses 
the QuickDraw procedure Set Origin to change the local coordinate system of the 
window so that the SurfWriter application can treat the upper-left corner of the 
document as again lying at (0,0). 


The Set Origin procedure takes two parameters: the first is a new horizontal coordinate 
for the window origin, and the second is a new vertical coordinate for the window origin. 


IMPORTANT 

Like ScrollRect, SetOrigin requires you to pass a horizontal 
coordinate and then a vertical coordinate. Notice that when you 
specify a point in the QuickDraw coordinate system, the opposite 
is true: you name the vertical coordinate first and the horizontal 
coordinate second. & 


Any time you are ready to update a window (such as after scrolling it), you can use 
GetControlValue to determine the current setting of the horizontal scroll bar and 
pass this value as the new horizontal coordinate for the window origin. Then use 
GetControlValue to determine the current setting of the vertical scroll bar and pass 
this value as the new vertical coordinate for the window origin. Using SetOriginin 
this fashion shifts the window’s local coordinate system so that the upper-left corner of 
the document is always at (0,0) when you redraw the document within its window. 


For example, after the user manipulates the vertical scroll bar to move (either up or 
down) to a location 100 pixels from the top of the document, the SurfWriter application 
makes the following call: 


SetOrigin(0, 100); 


Although the scrolling distance was —100, which is relative, the current setting for the 
scroll bar is now at 100. (Because you specify a point in the QuickDraw coordinate 
system by its vertical coordinate first and then its horizontal coordinate, the order of 
parameters to SetOrigin may be initially confusing.) 
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The left side of Figure 5-17 shows how the SurfWriter application uses the SetOrigin 
procedure to move the window origin to the point (100,0) so that the upper-left corner of 
the document is now at (0,0) in the window’s local coordinate system. This restores the 
document’s original coordinate space and makes it easier for the application to draw in 
the update region of the window. 


Figure 5-17 Updating the contents of a scrolled window 
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After restoring the document’s original coordinates, the SurfWriter application updates 
the window, as shown on right side of Figure 5-17. The application draws lines 16 
through 24, which it stores in its document record as beginning at (160,0) and ending 
at (250,0). 


To review what has happened up to this point: the user has dragged the scroll box 
one-half of the distance down the vertical scroll bar; the SurfWriter application 
determines that this distance amounts to a scroll distance of —100 pixels; the SurfWriter 
application passes this distance to Scrol1lRect, which shifts the bits in the window 
100 pixels upward and creates an update region for the rest of the window; the 
SurfWriter application passes the vertical scroll bar’s current setting (100 pixels) in a 
parameter to SetOrigin so that the document's local coordinates are used when the 
update region of the window is redrawn; and, finally, the SurfWriter application draws 
the text in the update region of the window. 


However, the window origin cannot be left at (100,0); instead, the SurfWriter application 
must use Set Origin to reset it to (0,0) after performing its own drawing, because the 
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Window and Control Managers always assume the window’s upper-left point is at (0,0) 
when they draw in a window. Figure 5-18 shows how the application uses SetOrigin 
to set the window origin back to (0,0) at the conclusion of its window-updating routine. 
After the update, the application begins processing events in its event loop again. 


Figure 5-18 Restoring the window origin to (0,0) 
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The left side of Figure 5-19 illustrates what happens when the user scrolls all the way 

to the end of the document—a distance of another 10 lines, or 100 pixels. After the 
SurfWriter application calls Scrol1Rect, the bottom 5 lines from the previous window 
display appear at the top of the new window and the bottom of the window becomes 

a new update region. Because the user has scrolled a total distance of 200 pixels, the 
application uses SetOrigin to change the window origin to (200,0), as shown on the 
right side of Figure 5-19. 


The left side of Figure 5-20 shows the SurfWriter application drawing in the update 
region of the window; the right side of the figure shows the SurfWriter application 
restoring the window origin to (0,0). 
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Figure 5-19 Scrolling to the end of a document 
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Figure 5-20 Updating a window's contents and returning the window origin to (0,0) 
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How your application determines a scrolling distance and how it then moves the bits in 
the window by this distance are explained in greater detail in the next two sections, 
“Scrolling in Response to Events in the Scroll Box” and “Scrolling in Response to Events 
in Scroll Arrows and Gray Areas.” “Drawing a Scrolled Document Inside a Window,” 
which follows these two sections, describes what your application should do in its 
window-updating code to draw in a window that has been scrolled. You can find more 
detailed information about the SetOrigin and Scroll1Rect procedures in Inside 
Macintosh: Imaging. 


So far, this discussion has assumed that you are scrolling in response to the user’s 
manipulation of a scroll bar. Most of the time, the user decides when and where to scroll. 
However, in addition to user manipulation of scroll bars, there are four cases in which 
your application must scroll through the document. Your application design must take 
these cases into account. 


ma When your application performs an operation whose side effect is to make a new 
selection or move the insertion point, you should scroll to show the new selection. For 
example, when the user invokes a search operation, your application locates the 
desired text. If this text appears in a part of the document that isn’t currently visible, 
you should scroll to show the selection. Such scrolling might also be necessary after 
the user invokes a paste operation. If the insertion point appears after the end of 
whatever was pasted, scroll until the selection and the new insertion point are visible. 


m When the user enters information from the keyboard at the edge of a window, you 
should scroll to incorporate and display the new information. The user’s focus will be 
on the new information, so it doesn’t make sense to maintain the document’s position 
and record the new information out of the user’s view. In general, a word processor 
scrolls one line of text, and a database or spreadsheet scrolls one field. Graphics 
applications should scroll to display an entire object when possible. Otherwise, 
determine how quickly your application can redraw the window contents during 
scrolling and adjust the scrolling to minimize blinking and redrawing. Try to ensure 
that the scrolling is sufficiently fast so as not to annoy users but not so fast as to 
confuse them. 


m When the user moves the cursor past the edge of the window while holding down the 
mouse button to make an extended selection, you should scroll the window in the 
direction of cursor movement. The rate of scrolling can be the same as if the user were 
holding down the mouse button on the corresponding scroll arrow. In some cases it 
makes sense to vary the scrolling speed so that it is faster as the user moves the cursor 
farther away from the edge of the window. 


m= Sometimes the user selects something, scrolls to a new location, and then tries to 
perform an operation on the selection. In this case, you should scroll so that the 
selection is showing before your application performs the operation. Showing the 
selection makes it clear to the user what is being changed. 


When designing the document-scrolling routines for your application, also try to keep 
the following user interface guidelines in mind: 


m Whenever your application scrolls automatically, avoid unnecessary scrolling. Users 
want to control the position of documents, so your application should move a 
document only as much as necessary. Thus, if part of a selection is already showing in 
a window, don’t scroll at all. One exception to this rule is when the hidden part of the 
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selection is more important than the visible part; then scroll to show the important 
part. For example, suppose a user selects a large block of text and only the bottom is 
currently visible. If the user then types a character, your application must scroll to the 
location of the newly typed characters so that they are visible. 


a If your application can scroll in one orientation to reveal the selection, don’t scroll in 
both orientations. That is, if you can scroll vertically to show the selection, don’t also 
scroll horizontally. 


m When you can show context on either side of a selection, it’s useful to do so. It’s 
also better to position a selection somewhere near the middle of a window than 
against a corner. When the selection is too large to fit in the window, it’s helpful to 
display unselected information at either the beginning or the end of the selection 
to provide context. 


Scrolling in Response to Events in the Scroll Box 


“Responding to Mouse Events in a Control” beginning on page 5-30 describes in 
general how to use FindControl and TrackControl in your event-handling code. 
Listing 5-18 shows how to use these routines to respond in particular to mouse events 
in a scroll bar. 


Listing 5-18 Responding to mouse events in a scroll bar 


PROCEDURE DoContentClick (window: WindowPtr; event: EventRecord) ; 
VAR 








mouse: Point; 

control: ControlHandle; 

part: Integer; 

myData: MyDocRecHnd; 

oldSetting: Integer; 

scrollDistance: Integer; 

windowType: Integer; 

BEGIN 
windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 
BEGIN 

myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
mouse := event.where; 
GlobalToLocal (mouse) ; {convert to local coordinates} 
part := FindControl(mouse, window, control); 


CASE part OF 
{handle all other parts first; handle scroll bar parts last} 


inThumb: {mouse-down in scroll box} 
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BEGIN {get scroll bar setting} 
oldSetting := GetControlValue (control); 
{let user drag scroll box around} 
part := TrackControl(control, mouse, NIL); 
{until user releases mouse button} 
IF part = inThumb THEN 
BEGIN {get new distance to scroll} 





scrollDistance := oldSetting - GetControlValue(control); 
IF scrollDistance <> 0 THEN 
IF control = myData**.vScrollBar THEN 
TEPinScroll(0, scrollDistance * 
myData®**.editRec**.lineHeight, 
myData**.editRec) ; 








TEPinScroll(scrollDistance, 0, myData**.editRec) ; 
END; {of handling mouse-up in scroll box} 
END; {of handling mouse-down in scroll box} 
inUpButton, inDownButton, inPageUp, in PageDown: 
{mouse-down in scroll arrows or gray areas} 
IF control = myData**.vScrollBar THEN 





{handle vertical scroll} 


part := TrackControl(control, mouse, @MyVerticalActionProc) 
ELSE {handle horizontal scroll} 
part := TrackControl(control, mouse, @MyHorzntlActionProc) ; 


OTHERWISE ; 
END; {of CASE part} 
HUnLock (Handle (myData) ); 





END; {of kMyDocWindowType} 
{handle other window types here} 
{of CASE windowType} 


When the user presses the mouse button while the cursor is in a visible, active scroll box, 
FindControl returns as its result the part code for a scroll box. That part code and the 
constant you can use to represent it are listed here: 


Constant Part code Control part 
inThumb 129 Scroll box 


As shown in Listing 5-18, when FindControl returns the value for inThumb, your 
application should immediately call GetControlValue to determine the current 
setting of the scroll bar. If the user drags the scroll box, you subtract from this setting the 
new current setting that becomes available when the user releases the mouse button, and 
you use this result for your scrolling distance. 
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After using Get Cont rolValue to determine the current setting of the scroll bar, use 
TrackControl to follow the movements of the cursor inside the scroll box and to drag 
a dotted outline of the scroll box in response to the user’s movements. 


When the user releases the mouse button, TrackControl returns inThumb if the cursor 
is still in the scroll box or 0 if the cursor is outside the scroll box. When TrackControl 
returns 0, your application does nothing. Otherwise, your application again uses 
GetControlValue to calculate the distance to scroll. 


Calculate the distance to scroll by calling Get Cont rolValue and subtracting the new 
current setting of the scroll bar from its previous setting, which you determine by calling 
GetControlValue before the user releases the mouse button. If this distance is not 0, 
you should move the bits in the window by this distance and update the contents of the 
rest of the window. 


Before scrolling, you must determine if the scroll bar is a vertical scroll bar or a horizon- 
tal scroll bar. As previously explained in this chapter, you should store handles to your 
scroll bars in a document record, one of which you create for every document. By 
comparing the field containing the vertical scroll bar handle, you can determine whether 
the control handle returned by FindControl is the handle to the vertical scroll bar. If 
so, the user has moved the scroll box of the vertical scroll box. If not, the user has moved 
the scroll box of the horizontal scroll bar. 


After determining which scroll bar contains the scroll box that the user has dragged, you 
move the document contents of the window by the appropriate scrolling distance. That 
is, for a positive scrolling distance in the vertical scroll bar, move the bits in the window 
down by that distance. When you update the window, this displays more lines from the 
top of the document—which is appropriate when the user moves the scroll box up. For a 
positive scrolling distance in the horizontal scroll bar, move the bits in the window to the 
right by that distance. When you update the window, this displays more lines from the 
left side of the document—which is appropriate when the user moves the scroll box to 
the left. (Remember: to scroll up or left, move the document down or right, both of which 
are in the positive direction.) 


For a negative scrolling distance in the vertical scroll bar (such as that shown in 

Figure 5-16 on page 5-46), move the bits in the window up by that distance. When you 
update the window, this displays more lines from the bottom of the document—which 
is appropriate when the user moves the scroll box down. For a negative scrolling distance 
in the horizontal scroll bar, move the bits in the window to the left by that distance. 
When you update the window, this displays more lines from the right side of the 
document—which is appropriate when the user moves the scroll box to the right. 
(Remember: to scroll down or right, move the document up or left, both of which are in 
the negative direction.) 


The previous examples in this chapter have shown an application that uses a TextEdit 
edit record to store monostyled text created by the user. For simple text-handling 

needs, TextEdit provides many routines that simplify your work; for example, the 
TEPinScrol1 procedure scrolls through the text in the view rectangle of an edit record 
by the number of pixels specified by your application; TEPinScro11 stops scrolling 
when the last line scrolls into the view rectangle. 
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The TEPinScroll1 procedure takes three parameters: the number of pixels to move the 
text horizontally, the number of pixels to move the text vertically, and a handle to an edit 
record. Positive values in the first two parameters move the text right and down, 
respectively, and negative values move the text left and up. 


The DoContentClick procedure, illustrated in Listing 5-18 on page 5-53, passes the 
scrolling distance in the second parameter of TEPinScrol1 for a vertical scroll bar, and 
it passes the scrolling distance in the first parameter for a horizontal scroll bar. 


Listing 5-16 on page 5-41 shows an application-defined routine, MyAd just BY, called by 
the SurfWriter sample application whenever it creates, opens, or resizes a window. This 
routine defines the current and maximum settings for a vertical scroll bar in terms of 
lines of text. 


The DoContentClick procedure on page 5-53 uses Get Cont rolValue to determine 
the control’s current setting—which for the vertical scroll bar DoContentClick 
calculates as some number of lines. When determining the vertical scroll bar’s scrolling 
distance, DoContentClick again calculates a value representing some number of lines. 


However, TEPinScrol11 expects pixels, not lines, to be passed in its parameters. There- 
fore, DoContentClick multiplies the scrolling distance (which it calculates as some 
number of lines of text) by the line height (which is maintained in the edit record for 
monostyled text as some number of pixels). In this way, DoContentClick passes a 
scrolling distance—in terms of pixels—to TEP inScrol1,as shown in this code fragment. 





IF control = myData**.vScrollBar THEN 
TEPinScroll(0, scrollDistance * myData**.editRec**%.lineHeight, 
myData’**.editRec) ; 


Figure 5-16 on page 5-46 illustrates a scrolling distance of -10 lines. If the line height 
is 10 pixels, the SurfWriter application passes —100 as the second parameter to 
TEPinScroll. 


The TEPinScroll procedure adds the scrolled-away area to the update region and 
generates an update event so that the text in the edit record’s view rectangle can be 
updated. In its code that handles update events for windows, the SurfWriter sample 
application then uses the TEUpdate procedure—as described in “Drawing a Scrolled 
Document Inside a Window” beginning on page 5-62— for its windows that include 
TextEdit edit records. 








Tolearn more about TEPinScroll, the TextEdit edit record, and other facilities offered 
by TextEdit, see Inside Macintosh: Text. 


The QuickDraw procedure Scrol1lRect is a more general-purpose routine for moving 
bits in a window when scrolling. If you use Scrol1Rect to scroll the bits displayed 
in the window, you should define a routine like DoGraphicsScrol1, shown in 
Listing 5-17 on page 5-47, and use it instead of TEPinScro11, which is used in 
Listing 5-18 on page 5-53. 


The ScrollRect procedure returns in the updat eRegion parameter the area that 
needs to be updated. The DoGraphicsScrol1 procedure shown in Listing 5-17 on 
page 5-47 then uses the QuickDraw procedure InvalRgn to add this area to the update 
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region, forcing an update event. In your code for handling update events, you draw in 
the area of the window from which ScrollRect has moved the bits, as described in 
“Drawing a Scrolled Document Inside a Window” beginning on page 5-62. 


When a mouse-down event occurs in the scroll arrows or gray areas of the vertical 
scroll bar, the DoContentClick routine in Listing 5-18 on page 5-53 calls 
TrackControl and passes it a pointer to an application-defined action procedure 
called MyVerticalActionProc. For the horizontal scroll bar, DoContentClick 
calls TrackControl and passes it a pointer to an action procedure called 
MyHorzntlActionProc. These action procedures are described in the next section. 


Scrolling in Response to Events in Scroll Arrows and Gray Areas 


With each click in a scroll arrow, your application should scroll by a distance of one 
unit (that is, by a single line, character, cell, or whatever your application deems 
appropriate) in the chosen direction. When the user holds the mouse button down 
while the cursor is in a scroll arrow, your application should scroll continuously by 
single units until the user releases the mouse button or until your application has 
scrolled as far as possible in the document. 


With each click in a gray area, your application should scroll in the appropriate direction 
by a distance of just less than the height or width of one window to show part of the 
previous window (thus placing the newly displayed material in context). When the user 
holds the mouse button down while the cursor is in a gray area, your application should 
scroll continuously in units of this distance until the user releases the mouse button or 
until your application has scrolled as far as possible in the document. 


When your application finishes scrolling, it should use Set Cont rolValue to move the 
scroll box accordingly. 


As previously described in this chapter, you use FindControl to determine when a 
mouse-down event has occurred in a control in one of your windows, and you use 
TrackControl to follow the movements of the cursor inside the control, to give the 
user visual feedback, and then to inform your application when the user releases the 
mouse button. 


When a mouse-down event occurs in the scroll arrows or the gray areas of an active 
scroll bar, FindControl returns as its result the appropriate part code. The part codes 
for the scroll arrows and gray areas, and the constants you can use to represent them, are 
listed here: 


Constant Part code Control part 





inUpButton 20 Up scroll arrow for a vertical scroll bar, left scroll arrow 
for a horizontal scroll bar 


inDownButton 21 Down scroll arrow for a vertical scroll bar, right scroll 
arrow for a horizontal scroll bar 


inPageUp 22 Gray area above scroll box for a vertical scroll bar, gray 
area to left of scroll box for a horizontal scroll bar 


inPageDown 23 Gray area below scroll box for a vertical scroll bar, gray 
area to right of scroll box for a horizontal scroll bar 
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When FindControl returns one of these part codes, your application should 
immediately call TrackControl. As long as the user holds down the mouse button 
while the cursor is in a scroll arrow, TrackCont rol highlights the scroll arrow, 
as shown in Figure 5-8 on page 5-12. When the user releases the mouse button, 
TrackControl removes the highlighting. 


For all of the other standard controls, as well as for the scroll box ina scroll bar, your 
application doesn’t respond until TrackCont rol reports a mouse-up event in the same 
control part where the mouse-down event initially occurred. However, for scroll arrows 
and gray areas, your application must respond by scrolling the document before 
TrackControl reports that the user has released the mouse button. When you call 
TrackControl for scroll arrows and gray areas, you must define an action procedure 
that scrolls appropriately until TrackControl reports that the user has released the 
mouse button. 


When the user releases the mouse button or moves the cursor away from the scroll 
arrow Or gray area, TrackCont rol returns as its result one of the previously listed 
values that represent the control part. As shown in Listing 5-18 on page 5-53, the 
DoContentClick procedure tests for the part codes inUpButton, inDownButton, 
inPageUp, and inPageDown to determine when a mouse-down event occurs in a 
scroll arrow or a gray area. 





When the user presses or holds down the mouse button while the cursor is in either 
the scroll arrow or the gray area of the vertical scroll bar, DoContentClick calls 
TrackControl and passes it a pointer to an application-defined action procedure 
called MyVerticalActionProc. For the horizontal scroll bar, DoContentClick 
calls TrackControl and passes it a pointer to an action procedure called 
MyVerticalActionProc. Intum, TrackControl calls these action procedures to 
scroll continuously until the user releases the mouse button. 


Note 

As an alternative to passing a pointer to your action procedure 

in a parameter to TrackCont rol, you can use the 
SetControlAction procedure to store a pointer to the action 
procedure in the cont rlAction field in the control record. When 
you pass Pointer (—1) instead of a procedure pointer to 
TrackControl, TrackControl uses the action procedure 
pointed to in the control record. # 


Listing 5-19 shows two sample action procedures: MyVert icalActionProc—which 
responds to mouse events in the scroll arrows and gray areas of a vertical scroll bar— 
and MyHorznt1lActionProc—which responds to those same events in a horizontal 
scroll bar. When TrackControl calls these action procedures, it passes a control handle 
and an integer representing the part of the control in which the mouse event occurred. 
Both MyVerticalActionProc and MyHorzntlActionProc use the constants 
inUpButton, inDownButton, inPageUp, and inPageDown to test for the control part 
passed by TrackControl. 
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Listing 5-19 Action procedures for scrolling through a text document 


PROCEDURE MyVerticalActionProc (control: ControlHandle; part: Integer); 
VAR 


scrollDistance: Integer; 
window: WindowPtr; 
myData: MyDocRecHnd; 
BEGIN 
IF part <> 0 THEN 
BEGIN 
window := control**.contrlOwner; {get the control's window} 


myData MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
CASE part OF 
inUpButton, inDownButton: {get one line to scroll} 
scrollDistance := 1; 
inPageUp, inPageDown: {get the window's height} 
BEGIN 
scrollDistance := (myData**.editRec®*.viewRect.bottom — 
myData*®*.editRec**.viewRect.top) 
DIV myData**.editRec**.lineHeight; 
{subtract 1 line so user sees part of previous window} 
scrollDistance := scrollDistance - 1; 
END; 
END; {of part CASE} 
IF (part = inDownButton) OR (part = inPageDown) THEN 
scrollDistance := -scrollDistance; 





MyMoveScrollBox(control, scrollDistance) ; 
IF scrollDistance <> 0 THEN {scroll by line or by window} 
TEPinScroll(0, scrollDistance * myData**.editRec**%.lineHeight, 
myData**.editRec) ; 
HUnLock (Handle (myData) ); 
END; 
END; {of MyVerticalActionProc} 


PROCEDURE MyHorzntlActionProc (control: ControlHandle; part: Integer); 
VAR 


scrollDistance: Integer; 
window: WindowPtr; 
myData: MyDocRecHnd; 
BEGIN 
IF part <> 0 THEN 
BEGIN 
window := control**.contrlOwner; {get the control's window} 
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myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
CASE part OF 
inUpButton, inDownButton: {get a few pixels} 








scrollDistance := kButtonScroll; 
inPageUp, inPageDown: {get a window's width} 
scrollDistance := myData**.editRec**.viewRect.right - 


myData**.editRec**.viewRect.left; 

END; {of part CASE} 
IF (part = inDownButton) OR (part = inPageDown) THEN 

scrollDistance := -scrollDistance; 
MyMoveScrollBox(control, scrollDistance) ; 
IF scrollDistance <> 0 THEN 

TEPinScroll(scrollDistance, 0, myData**.editRec) ; 
HUnLock (Handle (myData) ); 


END; 


END; 
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{of MyHorzntlActionProc} 


Each action procedure begins by determining an appropriate scrolling distance. For 
the scroll arrows in a vertical scroll bar, MyVerticalActionProc defines the 
scrolling distance as one line. For the gray areas in a vertical scroll bar, 
MyVerticalActionProc determines the scrolling distance in lines by dividing the 
window height by the line height; the window height is determined by subtracting 
the bottom coordinate of the view rectangle (defined in the edit record) from its top 
coordinate. Then MyVerticalActionProc subtracts 1 from this distance so that 
when the user presses the mouse button while the cursor is in a gray area, 
MyVerticalActionProc scrolls one line less than the total number of lines in 

the window. 


The MyVerticalActionProc procedure later multiplies these line distances by the 
line height to derive pixel distances to pass in parameters to TEPinScrol11. Also, 
MyVerticalActionProc turns these distances into negative values when the 
mouse-down event occurs in the lower scroll arrow or in the gray area below the 
scroll box. 


For the scrolling distance of the scroll arrows in horizontal scroll bars, 
MyHorzntlActionProc uses a predetermined pixel distance—roughly the 
document’s average character width. For the scrolling distance of the gray areas 
MyHorzntlActionProc uses the window width (which is derived by 
subtracting the left coordinate of the view rectangle from its right coordinate). The 
MyHorzntlActionProc routine turns these distances into negative values when 
the mouse-down event occurs in the right scroll arrow or in the gray area to the 
right of the scroll box. 


After calling MyMoveScrol11Box, an application-defined routine that moves the scroll 
box, both action procedures use TEPinScroll to move the text displayed in the 
window by the scrolling distance. (In this example, the SurfWriter application is 
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scrolling a simple monostyled text document stored as a TextEdit edit record. For 

a discussion of using the more general-purpose QuickDraw scrolling routine 
ScrollRect, see the previous section, “Scrolling in Response to Events in the Scroll 
Box” beginning on page 5-53.) 


The TEPinScroll procedure automatically creates an update region and invokes an 
update event. In its window-updating code, the SurfWriter application uses the 
TEUpdate procedure to draw the text in the update region, as shown in Listing 5-23 on 
page 5-65. 


The action procedures continue moving the text by the specified distances over and over 
until the user releases the mouse button and TrackCont rol completes. If there is no 
more area to scroll through, TEPinScrol1 automatically stops scrolling, as your 
application should if you implement your own scrolling routine. 





Listing 5-20 shows how the application-defined procedure MyMoveScrol1Box uses 
GetControlValue, GetControlMaximum, and SetControlValue to move the scroll 
box an appropriate distance while the action procedures scroll through the document. 
The MyMoveScrol11Box procedure uses Get Cont rolMaximum to determine the 
maximum scrolling distance, Get Cont rolValue to determine the current setting for 
the scroll box, and Set Cont rolValue to assign the new setting and move the scroll 
box. Use of the Set Cont rolMaximum and SetControlValue routines is described in 
“Determining and Changing Control Settings” beginning on page 5-37; 

Get Cont rolMaximun is described in detail on page 5-104. 


Listing 5-20 Moving the scroll box from the action procedures 





PROCEDURE MyMoveScrollBox (control: ControlHandle; 
scrollDistance: Integer); 











VAR 
oldSetting, setting, max: Integer; 

BEGIN 
oldSetting := GetControlValue (control); {get last setting} 
max := GetControlMaximum(control) ; {get maximum setting} 


{subtract action procs' scroll amount from last setting to get new setting} 





setting := oldSetting - scrollDistance; 
IF setting < 0 THEN 

setting := 0 
ELSE IF setting > max THEN 

setting := max; 


SetControlValue(control, setting); {assign new current setting} 
END; {of MyMoveScrol1lBox} 


The previous two sections have described how to move the bits displayed in the 
window; the next section describes how to draw into the update region. 
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Drawing a Scrolled Document Inside a Window 


The previous two sections have described how to use the QuickDraw procedure 
ScrollRect and the TextEdit procedure TEPinScrol11 in response to the user 
manipulating any of the five parts of a scroll bar. After using these or your own routines 
for moving the bits in your window, your application must draw into the update region. 
Typically, you use your own window-updating code for this purpose. 


Both InvalRect and TEPinScrol1, which are used in the examples shown earlier in 
this chapter, create update regions that cause update events. As described in the chapters 
“Window Manager” and “Event Manager” in this book, your application should draw in 
the update regions of your windows when it receives update events. If you create your 
own scrolling routine to use instead of ScrollRect or TEPinScrol1, you should 
guarantee that it generates an update event or that it explicitly calls your own 
window-updating routine. 


Listing 5-21 shows an application-defined routine, DoUpdate, that the SurfWriter 
application calls whenever it receives an update event. In this procedure, the application 
tests for two different types of windows: windows containing graphics objects and 
windows containing text created with TextEdit routines. 


Listing 5-21 An application-defined update routine 














PROCEDURE DoUpdate (window: WindowPtr) ; 











VAR 
windowType: Integer; 
BEGIN 
windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyGraphicsWindow: {window containing graphics objects} 
BEGIN 
BeginUpdate (window) ; 
MyDrawGraphicsWindow (window) ; 
EndUpdate (window) ; 
END; {of updating graphics windows} 
kMyDocWindow: {window containing TextEdit text} 
BEGIN 








BeginUpdate (window) ; 
MyDrawWindow (window) ; 
EndUpdate (window) ; 


4 





ND; {of updating TextEdit document windows} 
{handle other window types—modeless dialogs, etc.——here} 
END; {of windowType CASE} 

END; {of DoUpdate} 
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In this example, when the window requiring updating is of type kMyGraphicsWindow, 
DoUpdate uses another application-defined routine called MyDrawGraphicsWindow. 
When the window requiring updating is of type kMyDocWindow, DoUpdate uses 
another application-defined routine—namely, MyDrawWindow. Listing 5-22 shows 

the MyDrawGraphicsWindow routine and Listing 5-23 on page 5-65 shows the 
MyDrawWindow routine. 


Before drawing into the scrolled-away portion of the window, both of these routines 
use the QuickDraw, Window Manager, and Control Manager routines necessary for 
updating windows. (“Updating a Control” beginning on page 5-29 describes the 
UpdateControls procedure; see the chapter “Window Manager” in this book for a 
detailed description of how to use the rest of these routines to update a window.) 


Listing 5-22 Redrawing a window containing graphics objects 


PROCEDURE MyDrawGraphicsWindow (window: WindowPtr) ; 
VAR 
myData: MyDocRecHnd; 
i: Integer; 
BEGIN 
SetPort (window) ; 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
WITH window’ DO 
BEGIN 
EraseRect (portRect) ; 








UpdateControls (window, visRgn); 





DrawGrowlcon (window) ; 
SetOrigin (GetControlValue (myData**.hScrollBar) , 
GetControlValue (myData**.vScrollBar) ); 





1? > Ny 
WHILE i <= myData**.numObjects DO 
DrawMyObjects(portRect, myData®**.numObjects[i]); 





is:= i+ 1; 
END; {of WHILE} 
SetOrigin(0, 0); 
END; 
HUnLock (Handle (myData) ); 
END; {of MyDrawGraphicsWindow} 


The MyDrawGraphicsWindow routine uses the QuickDraw procedure SetOrigin to 
change the window origin by an amount equal to the scroll bar settings, so that the 
upper-left corner of the document lies at (0,0) in the window’s local coordinate system. 
The SurfWriter sample application performs this step so that its own drawing routines 
can draw into the correct area of the window. 
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Notice that MyDrawGraphicsWindow calls SetOrigin only after calling the necessary 
Window Manager and Control Manager routines, because the Window Manager and 
Control Manager always expect the window origin to be at (0,0). 


By using SetOrigin to change the window origin, MyDrawGraphicsWindow can treat 
the objects in its document as being located in a coordinate system where the upper-left 
corner of the document is always at (0,0). Then MyDrawGraphicsWindow calls another 
of its own routines, DrawMyOb jects, to draw the objects it has stored in its document 
record for the window. 


After performing all its own drawing in the window, MyDrawGraphicsWindow again 
uses Set Origin—this time to reset the window origin to (0,0) so that future Window 
Manager and Control Manager routines will draw into the correct area of the window. 


Figure 5-16 through Figure 5-20 earlier in this chapter help to illustrate how to use 
SetOrigin to offset the window’s coordinate system so that you can treat the objects 
in your document as fixed in the document’s own coordinate space. However, it is not 
necessary for your application to use Set Origin. Your application can leave the 
window’s coordinate system fixed and instead offset the items in your document by the 
amount equal to the scroll bar settings. The QuickDraw procedures Of fsetRect, 
OffsetRgn, SubPt, and AddPt, which are described in Inside Macintosh: Imaging, 
are useful if you pursue this approach. 


Note 

The SetOrigin procedure does not move the window’s clipping 
region. If you use clipping regions in your windows, use the QuickDraw 
procedure Get Clip to store your clipping region immediately after 
your first call to SetOrigin. Before calling your own window-drawing 
routine, use the QuickDraw procedure ClipRect to define a new 
clipping region—to avoid drawing over your scroll bars, for example. 
After calling your own window-drawing routine, use the QuickDraw 
procedure ClipRect to restore the original clipping region. You 

can then call SetOrigin again to restore the window origin to (0,0) 
with your original clipping region intact. See Inside Macintosh: 

Imaging for detailed descriptions of clipping regions and of these 
QuickDraw routines. @ 


The previous examples in this chapter have shown an application that uses a TextEdit 
edit record to store the information created by the user. For simple text-handling 

needs, TextEdit provides many routines that simplify your work; for example, the 
TEPinScroll procedure (used in Listing 5-18 on page 5-53 and Listing 5-19 on 

page 5-59) resets the view rectangle of text stored in an edit record by the amount of 
pixels specified by the application. The TEPinScrol1 procedure then generates an 
update event for the window. The TextEdit procedure TEUpdate should then be called 
in an application’s update routine to draw the update region of the scrolled window. 


Listing 5-23 shows an application-defined procedure, MyDrawWindow, that uses 
TEUpdate to update the text in windows of type kMyDocWindow. The TEUpdate 
procedure manages all necessary shifting of coordinates during window updating, so 
MyDrawWindow does not have to call SetOrigin as it does when it uses ScrollRect. 
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Listing 5-23 Redrawing a window after scrolling a TextEdit edit record 





PROCEDURE MyDrawWindow (window: WindowPtr) ; 
VAR 
myData: MyDocRecHnd; 
BEGIN 
SetPort (window) ; 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
WITH window’ DO 
BEGIN 
EraseRect (portRect) ; 

















UpdateControls (window, visRgn); 





DrawGrowlcon (window) ; 
TEUpdate (portRect, myData”**.editRec) ; 
END; 
HUnLock (Handle (myData) ); 
END; {of MyDrawWindow} 





Moving and Resizing Scroll Bars 


As described earlier in “Creating Scroll Bars” beginning on page 5-21, your application 
initially defines the location of a scroll bar within a window—and the size of the scroll 

bar—by specifying a rectangle in a control resource or in a parameter to NewControl. 
However, your application must be able to size and move the scroll bar dynamically in 
response to the user’s resizing of your windows. 


The chapter “Window Manager” in this book describes how to size windows when 
your application opens them and how to resize them—for example, in response to 

the user dragging the size box or clicking the zoom box. This section describes how to 
move and resize your scroll bars so that they fit properly on the right and bottom edges 
of your windows. 


When resizing your windows, your application should perform the following steps to 
adjust each scroll bar. 


1. Resize the window. 
2. Use the HideCont rol procedure to make each scroll bar invisible. 


3. Use the MoveCont rol procedure to move the vertical scroll bar to the right edge of 
the window, and use the MoveCont rol procedure to move the horizontal scroll bar 
to the bottom edge of the window. 


4. Use the SizeControl procedure to lengthen or shorten each scroll bar, so that each 
extends to the size box in the lower-right corner of the window. 


5. Recalculate the maximum settings for the scroll bars and use SetControlMaximum 
to update the settings and to redraw the scroll boxes appropriately. (Remember, you 
derive a scroll bar’s maximum setting by subtracting the length or width of its 
window from the length or width of the document.) 


Using the Control Manager 5-65 


CHAPTER 5 


Control Manager 


6. Use the ShowCont rol procedure to make each scroll bar visible in its new location. 


Figure 5-21 illustrates how to move and resize scroll bars in a resized window; if your 
application neglected to use the HideCont rol procedure, the user would see each of 
these steps as it took place. 


Figure 5-21 Moving and resizing scroll bars 
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Listing 5-14 on page 5-39 shows an application-defined routine, MyAdjustScrollBars, 
that is called when the user opens a new window, opens an existing document in a 
window, or resizes a window. 


When it creates a window, MyAdjustScrollBars stores handles to each scroll bar 

in a document record. By dereferencing the proper fields of the document record, 
MyAdjustScrollBars passes handles for the vertical and horizontal scroll bars to 
the HideControl procedure, which makes the scroll bars invisible. By making the scroll 
bars invisible until it has finished manipulating them, MyAdjustScrollBars ensures 
that the user won’t see the scroll bars blinking in different locations onscreen. 


When MyAdjustScrollBars needs to adjust the size or location of either of the scroll 
bars, it calls another application-defined routine, MyAdjustScrollSizes, which is 
shown in Listing 5-24. 


Listing 5-24 Changing the size and location of a window’s scroll bars 


CONST 
kScrollbarWidth = 16; {conventional width} 
kScrollbarAdjust = kScrollbarWidth - 1; {to align with window frame} 
kScrollTweek = 2; {to align scroll bars with size box} 


PROCEDURE MyAdjustScrollSizes (window: WindowPtr) ; 


VAR 
teRect: Rect; 
myData: MyDocRecHnd; 
teTop, teRight, teBottom,teLeft: Integer; 
BEGIN 


MyGetTERect (window, teRect); {calculate the teRect based on the } 
{ portRect, adjusted for the scroll bars} 
myData := MyDocRecHnd (GetWRefCon (window) ) ; 
HLock (Handle (myData) ); 
WITH window’*.portRect DO 








BEGIN 
teTop := top; 
teRight := right; 
teBottom := bottom; 
teLeft := left; 
END; 
WITH myData** DO 
BEGIN 
editRec®**.viewRect := teRect; {set the viewRect } 
MyAdjustViewRect (editRec) ; {snap to nearest line} 


{move the controls to match the new window size} 
MoveControl(vScrollBar, teRight - kScrollbarAdjust, -1); 
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SizeControl(vScrollBar, kScrollbarWidth, (teBottom —- teTop) - 


(kScrollbarAdjust - kScrollTweek) ); 


MoveControl(hScrollBar, -1, teBottom - kScrollbarAdjust) ; 
SizeControl(hScrollBar, (teRight - teLeft) - 





(kScrollbarAdjust - kScrollTweek), kScrollbarWidth) ; 


HUnLock (Handle (myData) ); 
{of MyAdjustScrollSizes} 


The MyAdjustScrol11Sizes routine uses the boundary rectangle of the window’s 
content region—which is stored in the portRect field of the window record—to 
determine the size of the window. To move the scroll bars to the edges of the window, 
MyAdjustScrollSizes uses the MoveCont rol procedure. 


The MoveCont rol procedure takes three parameters: a handle to the control being 
moved, the horizontal coordinate (local to the control’s window) for the new location of 
the upper-left corner of the control’s rectangle, and the vertical coordinate for that new 
location. The MoveCont rol procedure moves the control to this new location and 
changes the rectangle specified in the controlRect field of the control’s control record. 


In Listing 5-24, MyAdjustScrollSizes passes toMoveControl the handles to the 
scroll bars. (The SurfWriter sample application stores the handle in its document record 
for the window.) 


Figure 5-22 illustrates the location of a vertical scroll bar before it is moved to a new 
location within its resized window. 


To determine a new horizontal (that is, left) coordinate of the upper-left corner of the 
vertical scroll bar, MyAdjustScrol1Sizes subtracts 15 from the right coordinate of 
the window. As shown in Figure 5-23, this puts the right edge of the 16-pixel-wide scroll 
bar directly over the 1-pixel-wide window frame on the right side of the window. 


In Listing 5-24 on page 5-67,MyAdjustScroll1Sizes specifies —-1 as the vertical (that is, 
top) coordinate of the upper-left corner of the vertical scroll bar. As shown in Figure 5-23, 
this places the top edge of the scroll bar directly over the 1-pixel-wide line at the bottom 
of the title bar. (The bottom line of the title bar has a vertical value of —-1 in the window’s 
local coordinate system.) 


The MyAdjustScroll1Sizes routine specifies —1 as the horizontal coordinate of the 
upper-left corner of the horizontal scroll bar; this puts the left edge of the horizontal 
scroll bar directly over the 1-pixel-wide window frame. (The left edge of the window 
frame has a horizontal value of —1 in the window’s local coordinate system.) 


To fit your scroll bars inside the window frame properly, you should set the top 
coordinate of a vertical scroll bar at -1 and the left coordinate of a horizontal scroll bar 
at —1, unless your application uses part of the window’s scroll regions opposite the size 
box for displaying information or additional controls. For example, you may choose to 
display the current page number of the document in the lower-left corner of a window. 
In this case, specify a left coordinate so that the horizontal scroll bar doesn’t obscure 
this area. 
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Figure 5-22 A vertical scroll bar before the application moves it within a resized window 
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Figure 5-23 A vertical scroll bar after the application moves its upper-left point 
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See Macintosh Human Interface Guidelines for a discussion of appropriate uses of a 
window’s scroll areas for items other than scroll bars. 


To determine a new vertical coordinate for the upper-left corner of the horizontal scroll 
bar, MyAdjustScrol11Sizes subtracts 15 from the bottom coordinate of the window; 
this puts the bottom edge of the scroll bar directly over the window frame at the bottom 
of the window. 


The MoveCont rol procedure moves the upper-left corner of a scroll bar so that it’s in 
the proper location within its window frame. To make the vertical scroll bar fit the height 
of the window, and to make the horizontal scroll bar fit the width of the window, 
MyAdjustScrollSizes then uses the SizeControl procedure. 


The SizeControl procedure takes three parameters: a handle to the control being 
sized, a width in pixels for the control, and a height in pixels for the control. When 
resizing a vertical scroll bar, you adjust its height; when resizing a horizontal scroll bar, 
you adjust its width. 


When using SizeCont rol to adjust the vertical scroll bar, MyAdjustScrollSizes 
passes a constant representing 16 pixels for the vertical scroll bar’s width, which is the 
conventional size. 


To determine the proper height for this scroll bar, MyAdjustScrol1lSizes first derives 
the height of the window by subtracting the top coordinate of the window’s rectangle 
from its bottom coordinate. Then MyAdjustScrollSizes subtracts 13 pixels from this 
window height and passes the result to SizeControl as the height of the vertical scroll 
bar. The MyAdjustScrol1Sizes routine subtracts 13 pixels from the window height to 
leave room for the 16-pixel-high size box (at the bottom of the window) minus three 
1-pixel overlaps: one at the top of the window frame, one at the top of the size box, and 
one at the bottom of the size box. 


When using SizeControl to adjust the horizontal scroll bar, MyAdjustScrollSizes 
passes a constant representing 16 pixels—the conventional height of the horizontal scroll 
bar. To determine the proper width of this scroll bar, MyAdjustScrollSizes first 
derives the width of the window by subtracting the left coordinate of the window’s 
rectangle from its right coordinate. From this window width, MyAdjustScrollSizes 
then subtracts 13 pixels to allow for the size box (just as it does when determining the 
height of the vertical scroll bar). 


When MyAdjustScrollSizes completes, it returns toMyAdjustScrollBars, 
which then uses another of its own routines, MyAdjustScrollValues. In 

turn, MyAdjustScrollValues calls MyAdjustHV (shown in Listing 5-16 on 
page 5-41), which recalculates the maximum settings for the scroll bars and uses 
SetControlMaximum to update the maximum settings and redraw the scroll 
boxes appropriately. 


When MyAdjustHV completes, it eventually returns to the SurfWriter application’s 
MyAdjustScrollBars procedure, which then uses the ShowCont rol procedure 
to make the newly adjusted scroll bars visible again. 
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Defining Your Own Control Definition Function 


The Control Manager allows you to implement controls other than the standard ones 
(buttons, checkboxes, radio buttons, pop-up menus, and scroll bars). To implement 
nonstandard controls, you must define your own control definition functions. Typically, 
the only types of controls you might need to implement are sliders or dials, which are 
similar to scroll bars in that they graphically represent a range of values the user can set. 
As scroll bars have scroll boxes, your sliders and dials should have indicators for setting 
values and indicating current settings. 


Dials and sliders display the value, magnitude, or position of something, typically in 
some pseudo-analog form—for instance, the position of a sliding switch, the reading on 
a scale, or the angle of a needle on a gauge; the setting may be displayed digitally as 
well. The user should be able to change the control’s setting by dragging its indicator. 


Figure 5-24 illustrates a control supported by an application-defined control definition 
function. This control might be used to play back a sound or a QuickTime movie. The 
application might wish to define the control so that it plays the sound or movie at 
normal speed when the user clicks the control part on the left. The application might 
use the indicator along the slider to show what portion of the entire sound or movie 
sequence is currently playing. The application also allows the user to move quickly 
forward and backward through the sequence by dragging the indicator. Finally, the 
application might wish to define the two control parts on the far right so that they play 
backward (that is, “rewind”) and play forward quickly (that is, “fast forward”), 
respectively, when the user clicks them. 


Figure 5-24 A custom control 








Play Rewind | Fast Forward 


Note 
When you design a dial or slider, be sure to include meaningful labels 
that indicate to users the range and the direction of the indicator. 


Rather than create such a control yourself, you might be tempted to use a scroll bar for 
this purpose. Do not do so. Using a scroll bar for any purpose other than scrolling 
through a window compromises the consistency of the Macintosh interface. 


To define your own nonstandard control, you must write a control definition function, 
compile it as a resource of type 'CDEF', and include it in your resource file. (For more 
information about creating resources, see the chapter “Resource Manager” in Inside 
Macintosh: More Macintosh Toolbox.) 
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When you use Control Manager routines, they in turn call your control definition 
function as necessary. For example, for the control in Figure 5-24 to work properly, its 
control definition function must be able to 


m draw the control—including repositioning its indicator, making it inactive or active, 
and highlighting its control parts appropriately when mouse events occur in them 


m determine when a mouse-down event occurs in a control part 
m calculate the region of the control and its indicator 
m= move the indicator and update the control record with a new setting 


You can also use your control definition function to modify or expand certain Control 
Manager behaviors; for example, you can implement your own manner of dragging an 
indicator, and you can perform your own type of control initialization. 


For details about writing a control definition function, see “Defining Your Own Control 
Definition Function” beginning on page 5-109. 


Control Manager Reference 


This section describes the data structures, routines, and resources that are specific to the 
Control Manager. 


The “Data Structures” section shows the data structures for the control record, the 
auxiliary control record, the pop-up menu private data record, and the control color table 
record. The “Control Manager Routines” section describes Control Manager routines for 
creating controls, drawing controls, handling mouse events in controls, changing control 
settings and display, determining control settings, and removing controls. The 
“Application-Defined Routines” section describes the control definition function, which 
you need to provide when defining your own controls. The “Application-Defined 
Routines” section also describes the action procedure, which defines an action to be 
performed repeatedly as long as the user holds down the mouse button while the cursor 
is in a control. The “Resources” section describes the control resource and the control 
color table resource. 
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This section describes the control record, the auxiliary control record, the pop-up menu 
private data record, and the control color table record. 


Your application doesn’t specifically create the control record, the auxiliary control 
record, or the pop-up menu private data record; rather, your application simply 
creates any necessary resources and uses the appropriate Control Manager routines. 
The Control Manager creates these records as necessary. 
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You can use Control Manager routines to change values in the control record, or you 
can access and change its fields yourself; normally, you don’t change the values in 
the auxiliary control record. However, both the control record and the auxiliary 
control record have fields in which your application can store information as you 
deem appropriate. 


You can obtain the menu handle and the menu ID of the menu associated with a pop-up 
menu by dereferencing the cont rlData field of the control record, which, for pop-up 
menu controls, contains a handle to a pop-up private data record. This record contains 
the menu handle and the menu ID for the associated menu. 


You use a control color table record only when you want to use nonstandard colors for a 
control that you create while your application is running. Your application probably 
shouldn’t ever create a control color table record because you should use the system’s 
default colors to ensure consistency of the interface across applications. 


The Control Record 


When you create a control, the Control Manager incorporates the information you 
specify (either in the control resource or in the parameters of the NewCont rol function) 
into a control record, which is a data structure of type ControlRecord. The Control 
Manager functions you use for creating a control, GetNewCont rol andNewControl, 
return a handle to a newly allocated control record. Thereafter, your application 
normally refers to the control by this handle, because most other Control Manager 
routines expect a control handle as their first parameter. 


You can use Control Manager routines to determine and change several of the values in 
the control record, or you can access and change its fields yourself. 


TYPE ControlRecord = 
PACKED RECORD 





nextControl: ControlHandle; {next control} 
contrlOwner: WindowPtr; {control's window} 
contrlRect: Rect; {rectangle} 
contrlVis: Byte; {255 if visible} 
contrlHilite: Byte; {highlight state} 
contrlValue: Integer; {control's current setting} 
contrl1Min: Integer; {control's minimum setting} 
contr1Max: Integer; {control's maximum setting} 
contrlDefProc: Handle; {control definition function} 
contrlData: Handle; {data used by contrlDefProc} 
contrlAction: ProcPtr; {action procedure} 
contrlRfCon: LongInt; {control's reference value} 
contrlTitle: Str255; {control's title} 

END; 
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Field descriptions 
nextControl 


contrlOwner 


contrlRect 


contrlVis 


contrlHilite 


contrlValue 


contrlMin 


A handle to the next control associated with this control’s window. 
All the controls belonging to a given window are kept in a linked 
list, beginning in the controlList field of the window record and 
chained together through the next Control fields of the individual 
control records. The end of the list is marked by a NIL value; as new 
controls are created, they’re added to the beginning of the list. 


A pointer to the window to which this control belongs. 


The rectangle that completely encloses the control, in the local 
coordinates of the control’s window. You can use the MoveCont rol 
and SizeControl procedures to change the rectangle stored in 
this field. 


The invisible/visible state for the control. When the value of this 
field is 0, the Control Manager does not draw the control (its state is 
invisible); when the value of this field is 255, the Control Manager 
draws the control (its state is visible). Note that even when a control 
is visible, it might still be obscured from sight by an overlapping 
window or some other object. You can use the HideCont rol 
procedure to change this field from visible to invisible, and you can 
use the ShowCont rol procedure to change this field from invisible 
to visible. 


Specifies whether and how the control is to be displayed, indicating 
whether it’s active or inactive and, if active, whether it’s selected. 
The value of 0 signifies an active control that is not selected. A value 
from 1 through 253 signifies a part code designating the part of 

the (active) control to highlight, indicating that the user is pressing 
the mouse button while the cursor is in that part. The value 

255 signifies that the control is to be made inactive and drawn 
accordingly. The HiliteControl procedure lets you change the 
value of this field. 


The control’s current setting. For buttons, checkboxes, and radio 
buttons, 0 means the control is off and 1 means it’s on. For scroll 
bars and other sliders, cont r1Value may take any value within 
the range specified in the contr1Min and contr1Max fields. For 
pop-up menus, this value is the item number of the menu item 
chosen by the user; if the user hasn’t chosen a menu item, it is the 
item number of the first menu item. For other controls, you can use 
this field as you wish. You can use the Get Cont rolValue function 
to determine the value of this field, and you can use the 
SetControlValue procedure to change the value of this field. 
The control’s minimum possible setting. For on-and-off controls— 
like checkboxes and radio buttons—this value should be 0 (meaning 
that the control is off). For scroll bars and other sliders, this can be 
any appropriate minimum value. For controls—like buttons— 

that don’t retain a setting, this value should be 0. For pop-up 
menus, the Control Manager sets this field to 1. For other 

controls, you can use this field as you wish. You can use the 
GetControlMinimum function to determine the value of this field, 
and you can use the Set Cont rolMinimum procedure to change 

the value of this field. 
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contr1Max 


contrlDefProc 


contrlData 


contrlAction 


contrlRfCon 


contrlTitle 


The control’s maximum possible setting. For on-and-off controls 
like checkboxes and radio buttons, this value should be 1 (meaning 
that the control is on). For scroll bars and other sliders, this can be 
any appropriate maximum value. When you make the maximum 
setting of a scroll bar equal to its minimum setting, the control 
definition function automatically makes the scroll bar inactive. 
When you make the maximum setting exceed the minimum, the 
control definition function makes the scroll bar active again. For 
controls—like buttons—that don’t retain a setting, this value should 
be 1. For pop-up menus, the Control Manager sets this value to the 
number of items in the menu. For other controls, you can use this 
field as you wish. You can use the Get Cont rolMaximum function 
to determine the value of this field, and you can use the 
SetControlMaximum procedure to change the value of this field. 
A handle to the control definition function for this type of 

control. When you create a control, you identify its type with 

a control definition ID, which is converted into a handle to the 
control definition function and stored in this field. Thereafter, 

the Control Manager uses this handle to access the definition 
function; you should never need to refer to this field directly. 


Note 

In systems running in 24-bit mode, the high-order byte of the 
contrlDefProc field contains the variant, which the Control 
Manager gets from the control definition ID. 


Reserved for use by the control definition function, typically to hold 
additional information specific to a particular control type. For 
example, the control definition function for scroll bars uses this field 
for a handle to the region containing the scroll box. (If no more than 
4 bytes of additional information are needed, the definition function 
may store the information directly in the contr1Data field rather 
than using a handle.) The control definition function for pop-up 
menus uses this field to store a pop-up private data record, which is 
described on page 5-77. 

A pointer to the control’s action procedure, if any. The 
TrackControl function may call this procedure to respond to 

the user’s dragging of the control, and this procedure responds 

by repeatedly performing some action as long as the user holds 
down the mouse button. See the description of TrackControl 

on page 5-90 for more information about the action procedure. 

You can use the Get Cont rolAction function to determine the 
current value of this field and the Set Cont rolAction procedure 
to change it. 


The control’s reference value, which your application may use 
for any purpose. You can use the Get Cont rolReference 
function to determine the current value of this field and the 
SetControlReference procedure to change it. 

The control title, if any. You can use the GetControlTitle 
procedure to determine the current value of this field and the 
SetControlTitle procedure to change it. 
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The Auxiliary Control Record 


5-76 


For drawing all controls on systems running in 32-bit mode (which users can select using 
the Memory control panel), and for drawing controls that use colors other than the 
system default, the Control Manager creates and maintains a linked list of auxiliary 
control records, beginning in the global variable AuxCt 1Head. (There is only one global 
list for all controls in all windows, not a separate one for each window. Each window 
record, by contrast, has a handle to the list of its own controls.) 


An auxiliary control record is a data structure of type AuxCt1Rec. Your application 
doesn’t create and generally shouldn’t manipulate an auxiliary control record for a 
control; rather, you let the Control Manager create and manipulate the auxiliary control 
record. To create controls using colors other than the system default colors, use the 
SetControlColor procedure (described on page 5-101) or create a control color table 
resource (described on page 5-121) and let the Control Manager create the necessary 
auxiliary control records. There is, however, a field in the auxiliary control record that 
you can use to store information as you see fit; to get a handle to the auxiliary control 
record for a control, you can use the GetAuxiliaryControlRecord function 
(described on page 5-107). 


Each auxiliary control record is relocatable and resides in your application heap. Here is 
how an auxiliary control record is defined: 


TYPE AuxCtlRec = 








RECORD 
acNext: AuxCtlHandle; {handle to next AuxCtlRec} 
acOwner: ControlHandle; {handle to this record's control} 
acCTable: CCTabHandle; {handle to control color table } 

{ record} 

acFlags: Integer; {reserved} 
acReserved: LongInt; {reserved for future use} 
acRefCon: LongInt; {for use by application} 

END; 





Field descriptions 


acNext A handle to the next record in the auxiliary control list. 

acOwner The handle of the control to which this auxiliary record belongs; 
used as an ID field. 

acCTable The handle to a control color table record. (The control color table 
record is described on page 5-77.) 

acFlags Reserved for use by the Control Manager. 

acReserved Reserved for future expansion. 

acRefCon A reference value, which your application may use for any purpose. 


On systems using 32-bit mode, every control has its own auxiliary record, and 
the acCTable field contains a handle to the default control color table unless 
your application uses the Set Cont rolColor procedure or creates a control color 
table resource. 
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When drawing a control, the standard control definition functions search the linked list 
of auxiliary control records for the auxiliary control record whose acOwner field points 
to the control being drawn. If the standard control definition functions find an auxiliary 
control record for the control, they use the control color table specified in the acCTable 
field. If the standard control definition functions do not find an auxiliary control record 
for the control, they use the default system colors. 


The Pop-Up Menu Private Data Record 


You can obtain the menu handle and the menu ID of the menu associated with a pop-up 
menu by dereferencing the cont r1Data field of the pop-up menu’s control record. The 
contrl1Data field of a control record is a handle to a block of private information. For 
pop-up menu controls, this field is a handle to a pop-up private data record, which is a 
data structure of type popupPrivateData 





TYPE popupPrivateData = 








RECORD 
mHandle: MenuHandle; {handle to menu record} 
mID: Integer; {menu ID} 
mPrivate: ARRAY[0..0] OF SignedByte; {reserved} 
END; 





Field descriptions 


mHandle Contains a handle to the menu. 
m1ID The menu ID of the menu. 
mPrivate Reserved. 


You can use the standard pop-up control definition function to manage pop-up menus. 
For information on creating pop-up menus, see “Creating a Pop-Up Menu” beginning on 
page 5-25. See the chapter “Menu Manager” in this book for additional information. 


The Control Color Table Record 


By creating a control color table record and using the Set Cont rolColor procedure 
(described on page 5-101), your application can draw a control that uses colors other 
than the system default. (Alternatively, you can use nonstandard colors for a control you 
define in a control resource by creating a control color table resource—described on 
page 5-121—with the same resource ID as the control resource.) Be aware that controls in 
nonstandard colors may initially confuse your users. 


A control color table record is a data structure of type Ct 1CTab; it is defined as follows: 


TYPE CtlCTab = 





RECORD 
ccSeed: LongInt; {reserved; set to 0} 
ccRider: Integer; {reserved; set to 0} 
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ctSize: 


ctTable: 
END; 


Field descriptions 
ccSeed 
ccRider 


ctSize 


ctTable 


Integer; {number of ColorSpec records in next } 
{ field; 3 for standard controls} 
ARRAY[0..3] OF ColorSpec; 


Reserved in control color tables; set to 0. 
Reserved in control color tables; set to 0. 


The number of ColorSpec records in the next field. For controls 
drawn with the standard definition procedure, this field is always 3, 
because a standard control has three parts: frame, control body, and 
scroll box for scroll bars, and frame, control body, and text for other 
controls. If you want to supply ColorSpec records for additional 
parts, you must define your own controls, as described in “Defining 
Your Own Control Definition Function” beginning on page 5-109. 


An array of ColorSpec records. Each ColorSpec record describes 
the color of a different control part. Here is how a ColorSpec 
record is defined: 


TYPE ColorSpec = 





RECORD 
partIdentifier: Integer; {control part} 
partRGB: RGBColor; {color of part} 
END; 


The partIdentifier field of the ColorSpec record holds an 
integer that associates an RGBColor record with a particular part of 
the control. 


Three ColorSpec records are used to describe the parts of buttons, 
checkboxes, and radio buttons. Here are the constants that are used 
in the part Identifier fields of the three ColorSpec records 
used to describe these controls: 


{for buttons, checkboxes, and radio buttons} 
CONST cFrameColor = 0; {frame color} 
cBodyColor = 1; {fill color for body of } 
{ control} 
cTextColor = 2; {text color} 


When highlighted, buttons exchange their body and text colors; 
checkboxes and radio buttons change their appearance without 
changing colors. All three types indicate deactivation by dimming 
their text with no change in colors. 
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A number of ColorSpec records are used to describe the parts 
of scroll bars. Here are the constants that are used in the 
partIdentifier fields of the ColorSpec records used to 
describe the colors in scroll bars: 


CONST 

cFrameColor = 0; {Used to produce foreground color for scroll arrows } 
{ & gray area} 

cBodyColor = 1; {Used to produce colors in the scroll box} 

cArrowsColorLight = 5; {Used to produce colors in arrows & scroll bar } 
{ background color} 

cArrowsColorDark = 6; {Used to produce colors in arrows & scroll bar } 
{ background color} 

cThumbLight = 7; {Used to produce colors in scroll box} 

cThumbDark 8; {Used to produce colors in scroll box} 

cHiliteLight = 9; {Use same value as wHiliteColorLight in 'wctb'} 

cHiliteDark = 10; {Use same value as wHiliteColorDark in 'wctb'} 

cTitleBarLight = 11; {Use same value as wTitleBarLight in 'wctb'} 

cTitleBarDark = 12; {Use same value as wTitleBarDark in 'wctb'} 

cTingeLight = 13; {Use same value as wTingeLight in 'wctb'} 

cTingeDark = 14; {Use same value as wTingeDark in 'wctb'} 











When highlighted, scroll arrows are filled with the foreground 
color. A deactivated scroll bar shows no scroll box and displays its 
gray areas in a solid background color with no pattern. 


The ColorSpec records for a control can appear in any order. If 
you include a part identifier that is not found, the Control Manager 
uses the first ColorSpec record with an identifiable part. If you do 
not specify a part identifier, the Control Manager uses the default 
color for that part. 


The partRGB field of the ColorSpec record specifies an 
RGBColor record, which in turn specifies the red, green, and blue 
values for the part’s color. Use three 16-bit unsigned integers to give 
the intensity values for the three additive primary colors. Here is 
how the RGBColor record is defined: 








TYPE RGBColor = 


RECORD 
red: Integer; {red value for control part} 
green: Integer; {green value for control part} 
blue: Integer; {blue value for control part} 
END; 


When you create a control color table record, your application should not deallocate it if 
another control is still using it. 


When drawing a control, the standard control definition functions search the linked list 
of auxiliary control records for the record whose acOwner field points to that control. 
If a standard control definition function finds such a record, it uses the color table 
designated by that record; otherwise, it uses the default system colors. Each control 
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using colors other than the system default has its own auxiliary control record, even if 
that control uses the same control color table record as another control; two or more 
auxiliary records can share the same control color table record. (Auxiliary control records 
are described on page 5-76.) 


If you create a control definition function (as explained in “Defining Your Own Control 
Definition Function” beginning page 5-109), you can use color tables of any desired size 
and define their contents in any way you wish, except that part indices 1 through 127 are 
reserved for system definition. Any such nonstandard control definition function should 


bypass the defaulting mechanism by allocating an explicit auxiliary record for every 


control it creates. 
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This section describes the Control Manager routines for creating controls, drawing 
controls, tracking mouse events within controls, changing control display, determining 


control values, and removing controls. 


Some Control Manager routines can be accessed using more than one spelling of 

the routine’s name, depending on the interface files supported by your development 
environment. For example, Set Cont rolValue is also available as SetCt1Value. 
Table 5-1 provides a mapping between the previous name of a routine and its new 


equivalent name. 


Table 5-1 Mapping between new and previous names of Control Manager routines 
New name Previous name 
GetAuxiliaryControlRecord GetAuxCtl 
GetControlAction GetCtlAction 
GetControlMaximum GetCt1lMax 
GetControlMinimum GetCtlMin 
GetControlReference GetCRefCon 
GetControlTitle GetCTitle 
GetControlValue GetCtlValue 
GetControlVariant GetCVariant 
SetControlAction SetctlAction 
SetControlColor SetCtlColor 
SetControlMaximum SetCt1lMax 
SetControlMinimum SetctlMin 
SetControlReference SetCRefCon 
SetControlTitle SetcCTitle 
UpdateControls UpdtControl 
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Creating Controls 


To create a control, you should generally use the GetNewCont rol function, which takes 
information about the control from a control resource. Like menu resources, control 
resources isolate descriptive information from your application code, making your 
application easier to modify or translate. However, you can also use the NewControl 
function—for which you pass descriptive information in parameters—to create controls. 


Both GetNewCont rol andNewControl return a handle to the control record of the 
newly created control. Thereafter, your application normally refers to the control by this 
handle, because most other Control Manager routines expect a control handle as their 
first parameter. When you create scroll bars and pop-up menus, you should store their 
handles in one of your application’s own data structures for later reference. 


When you use the Dialog Manager to implement buttons, radio buttons, checkboxes, 
and pop-up menus in alert boxes and dialog boxes, the Dialog Manager automatically 
uses the Control Manager to create these controls for you. If you implement other 
controls in alert or dialog boxes, and whenever you implement controls—such as scroll 
bars—in your application’s windows, you must use either Get NewCont rol or 
NewCont rol to create these controls. 


GetNewControl 


To create a control from a description in a control resource ('CNTL'), use the 
GetNewControl function. 


FUNCTION GetNewControl (controlID: Integer; owner: WindowPtr) 
ControlHandle; 


controlID Theresource ID of a control resource. 


owner A pointer to the window in which you want to attach the control. 


DESCRIPTION 
The GetNewControl function creates a control record from the information in the 
specified control resource, adds the control record to the control list for the specified 
window, and returns as its function result a handle to the control. You use this handle 
when referring to the control in most other Control Manager routines. After making a 
copy of the control resource, GetNewCont rol releases the memory occupied by the 
original control resource before returning. 


If you provide a control color table resource with the same resource ID as the control 
resource, GetNewCont rol creates an auxiliary control record that uses the colors you 
specify in your control color table resource. If you don’t provide a control color table, 
GetNewControl creates an auxiliary control record that uses the default control color 
table if the computer is running in 32-bit mode. 
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The control resource specifies the rectangle for the control, its initial setting, its visibility 
state, its maximum and minimum settings, its control definition ID, a reference value, 
and its title (if any). After you use GetNewCont ro] to create the control, you can change 
the current setting, the maximum setting, the minimum setting, the reference value, and 
the title by using, respectively, the SetControlValue, SetControlMaximum, 
SetControlMinimum, SetControlReference, and SetControlTitle procedures 
You can use the MoveCont rol and SizeCont rol procedures to change the control’s 
rectangle. You can use the Get Cont rolValue, GetControlMaximum, 
GetControlMinimum, GetControlReference, and GetControlTitle functions to 
determine the control values. 








If the control resource specifies that the control should be visible, the Control Manager 
draws the control. If the control resource specifies that the control should initially be 
invisible, you can use the ShowCont rol procedure to make the control visible. 


If GetNewControl can’t read the control resource from the resource file, 
GetNewControl returns NIL. 


See Listing 5-1 on page 5-17 and Listing 5-5 on page 5-24 for examples of how to use 
GetNewControl to create, respectively, a button and a scroll bar. For information about 
windows’ control lists, see the chapter “Window Manager” in this book. 


NewControl 
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To create a control, you can use the NewCont rol function, which accepts in its 
parameters the information that describes the control. Generally, you should instead use 
the GetNewCont rol function to create a control. The Get NewCont rol function takes 
information about the control from a control resource, and as a result your application is 
easier to modify or translate into other languages. 


FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; 
title: Str255; visible: Boolean; 


value: Integer; min: Integer; max: Integer; 





procID: Integer; refCon: LongInt) 
ControlHandle; 


theWindow A pointer to the window in which you want to attach the control. All 
coordinates pertaining to the control are interpreted in this window’s 
local coordinate system. 


boundsRect The rectangle, specified in the given window’s local coordinates, that 
encloses the control and thus determines its size and location. 
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title 


visible 


value 


min 


max 


procID 


For controls that need a title—such as buttons, checkboxes, radio buttons, 
and pop-up menus—the string for that title. For controls that don’t use 
titles, pass an empty string. 





The visible/invisible state for the control. If you pass TRUE in this 
parameter, NewCont rol draws the control immediately, without using 
your window’s standard updating mechanism. If you pass FALSE, you 
must later use the ShowCont rol procedure to display the control. 





The initial setting for the control. For controls—such as buttons—that 
don’t retain a setting, pass 0 in this parameter. For controls—such as 
checkboxes and radio buttons—that retain an on-or-off setting, pass 0 in 
this parameter for a control that is off, and pass 1 for a control that is on. 
For controls—such as scroll bars and sliders—that can take a range of 
settings, specify whatever value is appropriate within that range. 


The minimum setting for the control. For controls—such as buttons—that 
don’t retain a setting, pass 0 in this parameter. For controls—such as 
checkboxes and radio buttons—that retain an on-or-off setting, use 0 
(meaning “off”) for the minimum value. For controls—such as scroll bars 
and sliders—that can take a range of settings, specify whatever minimum 
value is appropriate. 


The maximum setting for the control. For controls—such as buttons—that 
don’t retain a setting, pass 1 in this parameter. For controls—such as 
checkboxes and radio buttons—that retain an on-or-off setting, use 1 
(meaning “on”) for the maximum value. For controls—such as scroll bars 
and sliders—that can take a range of settings, specify whatever maximum 
value is appropriate. When you make the maximum setting of a scroll bar 
equal to its minimum setting, the control definition function 
automatically makes the scroll bar inactive; when you make the 
maximum setting exceed the minimum, the control definition function 
makes the scroll bar active again. 


The control definition ID, which leads to the control definition function 
for this type of control. The control definition function is read into 
memory if it isn’t already in memory. The control definition IDs and their 
constants for the standard controls are listed here. (You can also define 
your own control definition function and specify it the procID 
parameter.) 





CONST 
pushButProc = 0; {button} 
checkBoxProc = 1; {checkbox} 
radioButProc = 2; {radio button} 
useWFont = 8; {add to above to display } 
{ title in window font} 
scrollBarProc = 16; {scroll bar} 
popupMenuProc = 1008; {pop-up menu} 
popupFixedWidth = $0001; {add to popupMenuProc to } 


{ use a fixed-width ctrl} 
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popupUseAddResMenu = $0004; {add to popupMenuProc to } 
{ specify a value of } 
{ type ResType in the } 
{ contrlRfCon field of } 
{ the control record; } 
{ Menu Manager adds } 
{ resources of this type } 
{ to the menu} 
popupUseWFont = $0008; {add to popupMenuProc to } 
{ display in window font} 


refCon The control’s reference value, which is set and used only by 
your application. 


The NewCont rol function creates a control record from the information you specify in 
its parameters, adds the control record to the control list for the specified window, and 
returns as its function result a handle to the control. You use this handle when referring 
to the control in most other Control Manager routines. 


The NewCont rol function creates an auxiliary control record that uses the default 
control color table if the computer is running in 32-bit mode. 


If you need to use colors other than the default colors for the control, create a control 
color table record and use the Set Cont rolColor procedure. 


When specifying the rectangle in the boundsRect parameter, keep the following 
guidelines in mind: 


m Buttons are drawn to fit the rectangle exactly. To accommodate the tallest characters in 
the system font, allow at least a 20-point difference between the top and bottom 
coordinates of the rectangle. 


m For checkboxes and radio buttons, there should be at least a 16-point difference 
between the top and bottom coordinates. 


m By convention, scroll bars are 16 pixels wide, so there should be a 16-point difference 
between the left and right (or top and bottom) coordinates. (If there isn’t, the scroll bar 
is scaled to fit the rectangle.) A standard scroll bar should be at least 48 pixels long, to 
allow room for the scroll arrows and scroll box. 


The Control Manager displays control titles in the system font. When specifying a title 
for the control in the title parameter, make sure the title fits in the control’s rectangle; 
otherwise, NewControl truncates the title. For example, NewCont rol truncates the 
titles of checkboxes and radio buttons on the right in Roman scripts, and it centers and 
truncates both ends of the button titles. 


The Control Manager allows multiple lines of text in the titles of buttons, checkboxes, 
and radio buttons. When specifying a multiple-line title, separate the lines with the 
ASCII character code $0D (carriage return). If the control is a button, each line is 
horizontally centered, and the font leading is inserted between lines. (The height of each 
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line is equal to the distance from the ascent line to the descent line plus the leading of the 
font used. Be sure to make the total height of the rectangle greater than the number of 
lines times this height.) If the control is a checkbox or a radio button, the text is justified 
as appropriate for the user’s current script system, and the checkbox or button is 
vertically centered within its rectangle. 


After you use NewCont rol to create the control, you can change the current setting, 
the maximum setting, the minimum setting, the reference value, and the title by using, 
respectively, the SetControlValue, SetControlMaximum, SetControlMinimum, 
SetControlReference, and SetControlTitle procedures. You can use the 
MoveControl and SizeControl procedures to change the control’s rectangle. You 
can use the Get Cont rolValue, GetControlMaximum, GetControlMinimun, 
GetControlReference, and GetControlTitle functions to determine the 

control values. 











SPECIAL CONSIDERATIONS 


SEE ALSO 


The title of a button, checkbox, radio button, or pop-up menu normally appears in the 
system font, which in Roman script systems is 12-point Chicago. Do not use a smaller 
font; some script systems, such as KanjiTalk, require 12-point fonts. You should generally 
use the system font in your controls; doing so will simplify localization effort. However, 
if you absolutely need to display a control title in the font currently associated with the 
window’s graphics port, you can add the popupUseWFont constant to the pop-up menu 
control definition ID or add the useWF ont constant to the other standard control 
definition IDs. 


For information about windows’ control lists, see the chapter “Window Manager” in 
this book. Control definition IDs for other controls are discussed in “Defining Your Own 
Control Definition Function” beginning on page 5-109. 


Drawing Controls 


If you specify that a control is initially visible (either in the control resource or in a 
parameter to NewCont rol), the Control Manager draws the control inside its window 
when you call either the GetNewCont rol or the NewCont rol function. In either case, 
the Control Manager draws the control immediately, without using your window’s 
standard updating mechanism. If you specify that a control is invisible, you can use the 
ShowControl procedure when you want to draw the control. 


Note that even a visible control might be completely or partially obscured by 
overlapping windows or other objects. 


When your application receives an update event for a window that contains controls, 

use UpdateControls to redraw the necessary controls in the updated window. Note 
that the Dialog Manager automatically draws and updates controls in alert boxes and 

dialog boxes. 
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ShowControl 


DESCRIPTION 


To draw a control that is currently invisible, you can use the ShowCont rol procedure. 
PROCEDURE ShowControl (theControl: ControlHandle) ; 


theControl A handle to the control you want to make visible. 


If the specified control is invisible, the ShowCont rol procedure makes it visible and 
immediately draws the control within its window without using your window’s 
standard updating mechanism. If the control is already visible, ShowCont rol has 
no effect. 


You can make a control invisible in several ways: 
m You can specify that it’s invisible in its control resource. 
m You can specify that it’s invisible in a parameter to the NewControl function. 


m You can use the HideControl procedure to change a visible control into an 
invisible one. 


m You can directly change the cont r1Vis field of the control’s control record. 


SPECIAL CONSIDERATIONS 


SEE ASO 


The ShowControl procedure draws the control in its window, but the control can still 
be completely or partially obscured by overlapping windows or other objects. 


Listing 5-14 on page 5-39 illustrates the use of ShowCont rol to redisplay scroll bars 
after moving and resizing them. 


UpdateControls 
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To update controls in a window, you can use the UpdateCont rols procedure. The 
UpdateControls procedure is also available as the Updt Control procedure. 





PROCEDURE UpdateControls (theWindow: WindowPtr; 
updateRgn: RgnHandle) ; 











theWindow A pointer to the window containing the controls to update. 


updateRgn The update region within the specified window. 
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The UpdateControls procedure draws those controls that are in the specified update 
region. This procedure is faster than the DrawControls procedure, which draws all of 
the controls in a window. By contrast, UpdateControls draws only those controls in 
the update region. 


Your application should call UpdateControls upon receiving an update event for a 
window that contains controls. Window Manager routines such as SelectWindow, 
ShowWindow, and BringToFront do not automatically call DrawControls to display 
the window’s controls. They just add the appropriate regions to the window’s update 
region, generating an update event. 





In response to an update event, you normally call UpdateControls after using the 
Window Manager procedure BeginUpdate and before using the Window Manager 
procedure EndUpdate. You should set the updateRgn parameter to the visible region 
of the window’s port, as specified in the port’s visRgn field. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


If your application draws parts of a control outside of its rectangle, UpdateControls 
might not redraw it. 


The Dialog Manager handles update events for controls in alert boxes and dialog boxes. 





Listing 5-8 on page 5-30 illustrates the use of UpdateControls. The BeginUpdate and 
EndUpdate procedures are described in the chapter “Window Manager” in this book. 
See the chapter “Dialog Manager” in this book for more information about including 
controls in alert boxes and dialog boxes. 





DrawControls 


DESCRIPTION 


Although you should generally use the UpdateCont rols procedure to update controls 
in a window, you can instead use the DrawControls procedure. 





PROCEDURE DrawControls (theWindow: WindowPtr); 


theWindow A pointer toa window whose controls you want to display. 


The DrawControls procedure draws all controls currently visible in the specified 
window. The controls are drawn in reverse order of creation; thus, in case of overlapping 
controls, the control created first appears frontmost in the window. 
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Because the UpdateControls procedure redraws only those controls that need 
updating, your application should generally use it instead of DrawControls upon 
receiving an update event for a window that contains controls. 


You should call either DrawControls or UpdateControls after calling the Window 
Manager procedure BeginUpdate and before calling EndUpdate. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


The Dialog Manager automatically draws and updates controls in alert boxes and 
dialog boxes. 


Window Manager routines such as Se lect Window, ShowWindow, and BringToFront 
do not automatically update the window’s controls. They just add the appropriate 
regions to the window’s update region, generating an update event. 


See the chapter “Dialog Manager” in this book for more information about including 
controls in alert boxes and dialog boxes. See the chapter “Window Manager” in this book 
for more information about Window Manager routines. 


Draw1Control 


DESCRIPTION 


Although you should generally use the UpdateCont rols procedure to update controls, 
you can use the Draw1Cont rol procedure to update a single control. 


PROCEDURE DrawlControl (theControl: ControlHandle); 


theControl A handle to the control you want to draw. 


The Draw1Control procedure draws the specified control if it’s visible within its 
window. The UpdateControls procedure automatically calls Draw1Control. 


Handling Mouse Events in Controls 
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When the user presses the mouse button, your application receives a mouse-down event. 
Use the Window Manager function FindWindow to determine which window contains 
the cursor. If the mouse-down event occurred in the content region of your application’s 
active window, use the FindControl function to determine whether the cursor was 

in an active control and, if so, which control. To follow and respond to the cursor 
movements in that control, and then to determine in which part of the control the 
mouse-up event occurs, use the TrackCont rol function. 
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FindControl 


DESCRIPTION 


To determine whether a mouse-down event has occurred in a control and, if so, in which 
part of that control, use the FindControl function. 


FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; 
VAR theControl: ControlHandle): Integer; 


thePoint A point, specified in coordinates local to the window, where the 
mouse-down event occurred. 


theWindow A pointer to the window in which the mouse-down event occurred. 


theControl A handle to the control in which the mouse-down event occurred. 


When the user presses the mouse button while the cursor is in a visible, active control, 
FindControl returns as its function result a part code identifying the control’s part; the 
function also returns a handle to the control in the parameter theCont rol. The part 
codes that FindCont rol returns, and the constants you can use to represent them, are 
listed here: 


CONST inButton = 10; {button} 
inCheckBox = 11; {checkbox or radio button} 
inUpButton = 20; {up arrow for a vertical scroll } 


{ bar, left arrow for a horizontal } 
{ scroll bar} 

inDownButton = 21; {down arrow for a vertical scroll } 
{ bar, right arrow for a } 
{ horizontal scroll bar} 

inPageUp = 22; {gray area above scroll box for a } 
{ vertical scroll bar, gray area } 
{ to left of scroll box for a } 
{ horizontal scroll bar} 

inPageDown = 23; {gray area below scroll box for a } 
{ vertical scroll bar, gray area } 
{ to right of scroll box for a } 
{ horizontal scroll bar} 

inThumb = 129; {scroll box} 


The pop-up control definition function does not define part codes for pop-up menus. 
Instead, your application should store the handles for your pop-up menus when you 
create them. Your application should then test the handles you store against the handles 
returned by FindCont rol before responding to users’ choices in pop-up menus. 


If the mouse-down event occurs in an invisible or inactive control, or if it occurs outside 
a control, FindControl sets theCont rol toNIL and returns 0 as its function result. 
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When a mouse-down event occurs, your application should call FindControl after 
using the Window Manager function FindWindow to ascertain that a mouse-down 
event has occurred in the content region of a window containing controls. 


Before calling FindControl, use the GlobalToLocal procedure to convert the point 
stored in the where field (which describes the location of the mouse-down event) of the 
event record to coordinates local to the window. Then, when using FindCont rol, pass 
this point in the parameter thePoint. 


In the parameter t heWindow, pass the window pointer returned by the FindWindow 
function. 


After using FindControl to determine that a mouse-down event has occurred in 

a control, you generally use the TrackControl function, which automatically 
follows the movements of the cursor and responds as appropriate until the user releases 
the mouse button. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


The Dialog Manager automatically calls FindControl and TrackControl for 
mouse-down events inside controls of alert boxes and dialog boxes. 


The FindControl function also returns NIL in the parameter theCont rol and 0 as 
its function result if the window is invisible or if it doesn’t contain the given point. 
(However, FindWindow won't return a window pointer to an invisible window or to 
one that doesn’t contain the point where the mouse-down event occurred. As long as 
you call FindWindow before FindControl, this situation won't arise.) 


Listing 5-10 on page 5-33 illustrates the use of FindControl for detecting mouse-down 
events in a pop-up menu and a button; Listing 5-18 on page 5-53 illustrates its use for 
detecting mouse-down events in scroll bars. 


The FindWindow function is described in the chapter “Window Manager” in this book. 
The GlobalToLocal procedure is described in Inside Macintosh: Imaging. 


The event record is described in the chapter “Event Manager” in this book. See the 
chapter “Dialog Manager” in this book for more information about including controls in 
alert boxes and dialog boxes. 


TrackControl 
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To follow and respond to cursor movements in a control and then to determine the 
control part in which the mouse-up event occurs, use the TrackCont rol function. 


FUNCTION TrackControl (theControl: ControlHandle; 
thePoint: Point; actionProc: ProcPtr) 
Integer; 
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theControl A handle to the control in which a mouse-down event occurred. 


thePoint — A point, specified in coordinates local to the window, where the 
mouse-down event occurred. 


actionProc The action procedure. Typically, you should set this parameter to NIL 
for buttons, checkboxes, radio buttons, and the scroll box of a scroll bar; 
set this parameter to Pointer (-1) for pop-up menus; and set this 
parameter to the pointer to an action procedure for scroll arrows and 
gray areas of scroll bars, as well as for any other controls that require 
you to define additional actions to take while the user holds down the 
mouse button. 


The TrackControl function follows the user’s cursor movements in a control and 
provides visual feedback until the user releases the mouse button. The visual feedback 
given by TrackCont rol depends on the control part in which the mouse-down event 
occurs. When highlighting is appropriate, for example, TrackControl highlights the 
control part (and removes the highlighting when the user releases the mouse button). 
When the user holds down the mouse button while the cursor is in an indicator (such as 
the scroll box of a scroll bar) and moves the mouse, TrackCont rol responds by 
dragging a dotted outline of the indicator. 


The TrackControl function returns as its function result the control’s part code if the 
user releases the mouse button while the cursor is inside the control part, or 0 if the user 
releases the mouse button while the cursor is outside the control part. For control parts, 
the TrackControl function returns the same values (represented by the constants 
inButton, inCheckBox, inUpButton, inDownButton, inPageUp, inPageDown, 
and inThumb) returned by the FindControl function, as described on page 5-89. 





When TrackControl returns a value other than 0 as its function result, your applica- 
tion should respond as appropriate to a mouse-up event in that control part. When 
TrackControl returns 0 as its function result, your application should do nothing. 


If the user releases the mouse button when the cursor is in an indicator such as a scroll 
box, TrackControl calls the control’s control definition function to reposition the 
indicator. The control definition function for scroll bars, for example, responds to the 
user dragging a scroll box by redrawing the scroll box, calculating the control’s current 
setting according to the new relative position of the scroll box, and storing the current 
setting in the control record. Thus, if the minimum and maximum settings are 0 and 10, 
and the scroll box is in the middle of the scroll bar, 5 is stored as the current setting. For a 
scroll bar, your application must then respond by scrolling to the corresponding relative 
position in the document. 


Generally, you use TrackCont rol after using the FindControl function. In the 
parameter theControl of TrackControl, pass the control handle returned by the 
FindControl function, and in the parameter thePoint, supply the same point you 
passed to FindControl (that is, a point in coordinates local to the window). 
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While the user holds down the mouse button with the cursor in one of the standard con- 
trols, TrackControl performs the following actions, depending on the value you pass 
in the parameter actionProc. (For other controls, what you pass in this parameter de- 
pends on how you define the control.) 


m If you passNILin the actionProc parameter, TrackCont rol uses no action 
procedure and therefore performs no additional actions beyond highlighting the 
control or dragging the indicator. This is appropriate for buttons, checkboxes, radio 
buttons, and the scroll box of a scroll bar. 


m If you pass a pointer to an action procedure in the act ionProc parameter, you must 
provide the procedure, and it must define some action that your application repeats as 
long as the user holds down the mouse button. This is appropriate for the scroll 
arrows and gray areas of a scroll bar. 


m Ifyou pass Pointer (-1) inthe actionProc parameter, TrackControl looks in 
the contrlAction field of the control record for a pointer to the control’s action 
procedure. This is appropriate when you are tracking the cursor in a pop-up menu. 
(You can use the Get Cont rolAction function to determine the value of this field, 
and you can use the Set Cont rolAction procedure to change this value.) If the 
contrlAction field of the control record contains a procedure pointer, 
TrackControl uses the action procedure it points to; if the field of the control record 
also contains the value Pointer (-1), TrackControl calls the control’s control 
definition function to perform the necessary action; you may wish to do this if you 
define your own control definition function for a custom control. If the field of the 
control record contains the value NIL, TrackControl performs no action. 


SPECIAL CONSIDERATIONS 


When you need to handle events in alert and dialog boxes, Dialog Manager routines 
automatically call FindControl andTrackControl. 


ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 
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The TrackControl function invokes the Window Manager function DragGrayRgn, so 
you can use the global variables DragHook and DragPattern. 


See “Defining Your Own Action Procedures” beginning on page 5-115 for information 
about an action procedure to specify in the act ionProc parameter. See “Defining Your 
Own Control Definition Function” beginning on page 5-109 for information about 
creating a control definition function. 

Listing 5-11 on page 5-36, Listing 5-12 on page 5-37, Listing 5-13 on page 5-38, 

and Listing 5-18 on page 5-53 illustrate the use of TrackCont rol for responding to 
mouse-down events in, respectively, a button, a pop-up menu, a checkbox, and a 

scroll bar. 


See the chapter “Dialog Manager” in this book for more information about including 
controls in alert boxes and dialog boxes. 
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The TestControl function is called by the FindControl and TrackControl 
functions—normally you won’t need to call it yourself. However, should you ever need 
to determine the control part in which a mouse-down event occurred, you can use the 
TestControl function. 


FUNCTION TestControl (theControl: ControlHandle; thePt: Point) 
Integer; 


theControl A handle to the control in which the mouse-down event occurred. 


thePt The point, in a window’s local coordinates, where the mouse-down 
event occurred. 


When the control specified by the parameter theCont rol is visible and active, 
TestControl tests which part of the control contains the point specified by the 
parameter thePt. For its function result, Test Cont rol returns the part code of the 
control part, or 0 if the point is outside the control. 


If the control is invisible or inactive, TestControl returns 0. 


Changing Control Settings and Display 


In response to user actions, you often need to change the settings, highlight states, sizes, 
and locations of your controls. Whenever your application calls the TrackControl 
function, the Control Manager automatically manipulates control display as appropriate 
as the user presses and releases the mouse button. For example, TrackControl calls the 
HiliteControl procedure to highlight buttons; for scroll bars, TrackCont rol calls 
the DragControl procedure to move an outline of the scroll box in a scroll bar and the 
SetControlValue procedure to change the scroll bar’s current setting and redraw the 
scroll box in its new location. (Note that the Dialog Manager automatically calls 
TrackControl for controls in alert boxes and dialog boxes. See the chapter “Dialog 
Manager” in this book for more information.) 


When the user releases the mouse button while the cursor is in a control, your 
application often needs to change its setting. When the user clicks a checkbox, for 
example, your application must change its setting to on or off, and the Control Manager 
automatically draws or removes an X in the checkbox. 


There are other instances when you must change the settings and display of a control. 
For example, when the user changes the size of a window that contains a scroll bar, you 
need to resize and move the scroll bar accordingly. 


For controls whose values the user can set, you can use the SetControlValue 
procedure to change the control’s setting and redraw the control accordingly. When 
you need to change the maximum setting of a scroll bar or a dial, you can use the 


Control Manager Reference 5-93 


CHAPTER 5 


Control Manager 


SetControlMaximum procedure; if you need to change the minimum setting, you 

can use the Set Cont rolMinimum procedure. If you need to change a control title, 

you can use the SetCont rolTitle procedure. You can use the HideControl 
procedure to make a control invisible. When you need to make a control inactive 

(such as when its window is not frontmost) or in any other way change the highlighting 
of a control, you can use the HiliteControl procedure. 


To move a scroll bar, you use the MoveCont rol and SizeCont rol procedures. 


Although it’s not recommended, you can also change a control’s default colors to those 
of your own choosing by using the Set Cont rolColor procedure. 


To invoke a continuous action while the user holds down the mouse button, you 

can specify an action procedure (described in “Defining Your Own Action Procedures” 
beginning on page 5-115) in a parameter to TrackControl. Under certain circum- 
stances, you can use the Set Cont rolAction procedure to change the control's action 
procedure, though you should rarely if ever need to. 


SetControl Value 


DESCRIPTION 
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To change the current setting of a control and redraw it accordingly, you can use the 
SetControlValue procedure. The Set Cont rolValue procedure is also available as 
the SetCt1Value procedure. 


PROCEDURE SetControlValue (theControl: ControlHandle; 
theValue: Integer); 








theControl A handle to the control whose current setting you wish to change. 


theValue Thenew setting for the control. 


The SetControlValue procedure changes the cont r1Value field of the control 
record to the specified value and redraws the control to reflect the new setting. For 
checkboxes and radio buttons, the value 1 fills the control with the appropriate mark, 
and 0 removes the mark. For scroll bars, Set Cont rolValue redraws the scroll box 
where appropriate. 


If the specified value is less than the minimum setting for the control, 
SetControlValue sets the control to its minimum setting; if the value is greater 
than the maximum setting, Set Cont rolValue sets the control to its maximum. 


When you create a control, you specify an initial setting either in the control resource or 
in the value parameter of the NewCont rol function. To determine a control’s current 
setting before changing it in response to a user’s click in that control, use the 
GetControlValue function. 
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Listing 5-13 on page 5-38 illustrates the use of Set Cont rolValue to change the setting 
of a checkbox. Listing 5-16 on page 5-41 and Listing 5-20 on page 5-61 illustrate the use 
of SetControlValue to change the setting of a scroll bar. 


SetControlMinimum 


DESCRIPTION 


To change the minimum setting of a control and redraw its indicator or scroll box 
accordingly, you can use the Set Cont rolMinimum procedure. The 
SetControlMinimum procedure is also available as the Set Ct 1Min procedure. 


PROCEDURE SetControlMinimum (theControl: ControlHandle; 
minValue: Integer); 


r 





theControl A handle to the control whose minimum setting you wish to change. 


minValue Thenew minimum setting. 


The SetControlMinimum procedure changes the cont r1Min field of the control 
record to the setting you specify in the minValue parameter and redraws its indicator 
or scroll box to reflect its new range. 


When you create a control, you specify an initial minimum setting either in the control 
resource or in the min parameter of the NewCont rol function. To determine a control’s 
current minimum setting, use the Get Cont rolMinimum function. 


SetControl|Maximum 


DESCRIPTION 


To change the maximum setting of a control and redraw its indicator or scroll 
box accordingly, you can use the Set Cont rolMaximum procedure. The 
SetControlMaximum procedure is also available as the Set Ct 1Max procedure. 














PROCEDURE SetControlMaximum (theControl: ControlHandle; 
maxValue: Integer); 


theControl A handle to the control whose maximum setting you wish to change. 


maxValue The new maximum setting. 


The SetCont rolMaximum procedure changes the cont r1Max field of the control 
record to the setting you specify in the maxValue parameter and redraws its indicator 
or scroll box to reflect its new range. 
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When you create a control, you specify an initial maximum setting either in the control 
resource or in the max parameter of the NewCont rol function. To determine a control’s 
current maximum setting, use the Get Cont rolMaximum function. 


When you set the maximum setting of a scroll bar equal to its minimum setting, the 
control definition function makes the scroll bar inactive; when you make the maximum 
setting exceed the minimum, the control definition function makes the scroll bar active 
again. 


Listing 5-16 on page 5-41 illustrates the use of Set Cont rolMaximum to specify the 
maximum setting for a scroll bar. 


SetControlTitle 


DESCRIPTION 
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To change the title of a control and redraw the control accordingly, use the 
SetControlTitle procedure. The Set ControlTitle procedure is also available as 
the SetCTitle procedure. 





PROCEDURE SetControlTitle (theControl: ControlHandle; 
title: Str255); 











theControl A handle toa control, the title of which you want to change. 


title The new title for the control. 


The SetControlTitle procedure changes the cont r1Title field of the control 
record to the given string and redraws the control, using the system font for the 
control title. 


The Control Manager allows multiple lines of text in the titles of buttons, checkboxes, 
and radio buttons. When specifying a multiple-line title, separate the lines with the 
ASCII character code $0D (carriage return). If the control is a button, each line is 
horizontally centered, and the font leading is inserted between lines. (The height of each 
line is equal to the distance from the ascent line to the descent line plus the leading of the 
font used. Be sure to make the total height of the rectangle greater than the number of 
lines times this height.) If the control is a checkbox or a radio button, the text is justified 
as appropriate for the user’s current script system, and the checkbox or button is 
vertically centered within its rectangle. 


When you create a control, you specify an initial title either in the control resource or in 
the title parameter of the NewCont rol function. To determine a control's current title, 
use the Get Cont rolTitle procedure. 
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HideControl 


DESCRIPTION 


To make a control invisible, before adjusting its size and location, for example, use the 
HideControl procedure. 


PROCEDURE HideControl (theControl: ControlHandle); 


theControl A handle to the control you want to hide. 


The HideControl procedure makes the specified control invisible by changing the 
value of the cont r1Vis field of the control record and removing the control from the 
screen. To fill the region previously occupied by the control, HideCont rol uses the 
background pattern of the window’s graphics port. It also adds the control’s rectangle to 
the window’s update region, so that anything else that was previously obscured by the 
control will reappear on the screen. If the control is already invisible, HideCont rol has 
no effect. 


To make the control visible again, you can use the ShowCont rol procedure. 


SPECIAL CONSIDERATIONS 


The MoveControl and SizeControl procedures both call HideCont rol and 
ShowControl automatically. However, so that the control will not blink on the screen 
when you make both of these calls, you should use HideCont rol to make the control 
invisible until you are finished manipulating it, and then use ShowCont rol. 


SEE ALSO 
Listing 5-14 on page 5-39 illustrates the use of HideCont rol before adjusting scroll bar 
settings and locations. 

MoveControl 


To move a control within its window, you can use the MoveCont rol procedure. 


PROCEDURE MoveControl (theControl: ControlHandle; 
h: Integer; v: Integer); 


theControl A handle to the control you wish to move. 


h The horizontal coordinate (local to the control’s window) of the new 
location of the upper-left corner of the control’s rectangle. 


v The vertical coordinate (local to the control’s window) of the new 
location of the upper-left corner of the control’s rectangle. 
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The MoveCont rol procedure moves the control to the new location specified by the h 
and v parameters, using them to change the rectangle specified in the cont rlRect field 
of the control’s control record. When the control is visible, MoveCont rol first hides it 
and then redraws it at its new location. 


For example, if the user resizes a document window that contains a scroll bar, your 
application can use MoveCont rol to move the scroll bar to its new location. 





SEE ALSO 
Listing 5-24 on page 5-67 illustrates the use of MoveCont rol to change the location of a 
scroll bar. 
SizeControl 
To change the size of a control’s rectangle, use the SizeControl procedure. 
PROCEDURE SizeControl (theControl: ControlHandle; 
h: Integer; v: Integer); 
theControl A handle to the control you wish to resize. 
w The new width, in pixels, of the resized control. 
h The new height, in pixels, of the resized control. 
DESCRIPTION 
The SizeControl procedure changes the rectangle specified in the cont rlRect field 
of the control’s control record. The lower-right corner of the rectangle is adjusted so 
that it has the width and height specified by the wand h parameters; the position of the 
upper-left corner is not changed. If the control is currently visible, it’s first hidden and 
then redrawn in its new size. The SizeCont rol procedure uses HideCont rol, which 
changes the window’s update region. 
SEE ALSO 
Listing 5-24 on page 5-67 illustrates the use of SizeControl to change the size of a 
scroll bar. 
HiliteControl 
If you need to change the highlighting of a control, you can use the HiliteControl 
procedure. 
PROCEDURE HiliteControl (theControl: ControlHandle; 
hiliteState: Integer); 
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theControl A handle to the control. 


hiliteState 
A value from 0 through 255 to signify the highlighting of the control. 
The value of 0 signifies no highlighting for the active control. A value 
from 1 through 253 signifies a part code designating the part of the 
(active) control to highlight. (Part codes are explained in the description 
of FindControl on page 5-89.) The value 255 signifies that the control is 
to be made inactive and drawn accordingly. 


DESCRIPTION 


The HiliteControl procedure calls the control definition function to redraw the 
control with the highlighting specified in the hiliteState parameter. The 
HiliteControl procedure uses the value in this parameter to change the value 
of the contr1Hilite field of the control’s control record. 


Except for scroll bars (which you should hide using the HideCont rol procedure), you 
should use HiliteControl to make all controls inactive when their windows are not 
frontmost. The TrackCont rol function automatically uses the HiliteControl 
procedure as appropriate; when you use TrackCont rol, you don’t need to call 
HiliteControl. 


SPECIAL CONSIDERATIONS 


The value 254 should not be passed in the hiliteState parameter; this value is 
reserved for future use. 


SEE ALSO 
The chapter “Dialog Manager” in this book provides several examples of the use of 
HiliteControl. 

DragControl 


If you need to draw and move an outline of a control or its indicator (such as the scroll 
box of a scroll bar) while the user drags it, you can use the DragCont rol procedure. 





PROCEDURE DragControl (theControl: ControlHandle; 
startPt: Point; 
limitRect: Rect; slopRect: Rect; 


axis: Integer); 


theControl A handle to the control to drag. 


startPt The location of the cursor, expressed in the local coordinates of the 
control’s window, at the time the user first presses the mouse button. 
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limitRect A rectangle—which should normally coincide with or be contained in the 
window’s content region—delimiting the area in which the user can drag 
the control’s outline. 


slopRect A rectangle that allows some extra space for the user to move the mouse 
while still constraining the control within the rectangle specified in the 
limitRect parameter. 


axis The axis along which the user may drag the control’s outline. The 
following list shows the constants you can use—and the values they 
represent—for constraining the motion along an axis: 


CONST 
noConstraint = 0; {no constraint} 
hAxisOnly = 1; {drag along horizontal axis only} 
vAxisOnly = 2; {drag along vertical axis only} 


DESCRIPTION 


The DragCont rol procedure moves a dotted outline of the control around the screen, 
following the movements of the cursor until the user releases the mouse button. When 
the user releases the mouse button, DragCont rol calls MoveCont rol. In turn, 
MoveControl moves the control to the location to which the user dragged it. 


The TrackControl function automatically uses the DragCont rol procedure as 
appropriate; when you use TrackCont rol, you don’t need to call DragControl. 


The startPt, limitRect, slopRect, and axis parameters have the same meaning as 
for the Window Manager function DragGrayRgn. 


SPECIAL CONSIDERATIONS 


Before tracking the cursor, DragCont rol calls the control definition function. If you 
define your own control definition function, you can specify custom dragging behavior. 


ASSEMBLY-LANGUAGE INFORMATION 


Like TrackControl, DragControl invokes the Window Manager function 
DragGrayRgn, so you can use the global variables DragHook and DragPattern. 


SEE ALSO 


For information about creating your own control definition functions, see “Defining Your 
Own Control Definition Function” beginning on page 5-109. See the description of the 
DragGrayRgn function in the chapter “Window Manager” in this book for a more 
complete discussion of the startPt, limitRect, slopRect, and axis parameters, 
which are used identically in the DragCont rol function. 
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SetControlColor 


DESCRIPTION 


To draw a control using colors other than the default colors used by system software, 
you can use the SetControlColor procedure. The Set Cont rolColor procedure is 
also available as the SetCt1Color procedure. 


PROCEDURE SetControlColor (theControl: ControlHandle; 
newColorTable: CCTabHandle); 


theControl A handle to the control whose colors you wish to change. 


newColorTable 
A handle to a control color table record. 


The SetControlColor procedure changes the color table for the specified control. If 
the control currently has no auxiliary control record, Set Cont rolColor creates one 
that includes the control color table record specified in the parameter newColorTable 
and adds the auxiliary control record to the head of the auxiliary control list. If there 

is already an auxiliary record for the control, SetControlColor replaces its color 
table with the contents of the control color table record specified in the parameter 
newColorTable. 


To use nonstandard colors for a control, you must create a control color table, either by 
creating a color control table record and calling Set Cont rolColor or by creating a 
control color table resource. Generally, you use Set Cont rolColor when you create 

a control using NewCont rol and want to use nonstandard colors for it or when you 
change any control’s colors after you've created it. When you want to use nonstandard 
colors for those controls you create in a control ('CNTL') resource, you should create a 
control color table ('cctb') resource with the same resource ID as the control resource. 


A control whose colors you set with Set Cont rolColor should initially be invisible. 
After using SetControlColor to set the control’s colors, use the ShowCont rol 
procedure to make the control visible. 


SPECIAL CONSIDERATIONS 


On color monitors, the Control Manager automatically draws controls so that they match 
the colors of the controls used by system software. Be aware that nonstandard colors in 
your controls may initially confuse your users. 


When you create a control color table record, your application should not deallocate it if 
another control is still using it. 
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SetControlAction 


DESCRIPTION 


If you set the action procedure to Pointer (-1) when you use TrackCont rol, you can 
use the SetCont rolAction procedure to set or change the action procedure. The 
SetControlAction procedure is also available as the Set Ct lAct ion procedure. 


PROCEDURE SetControlAction (theControl: ControlHandle; 


actionProc: ProcPtr); 


theControl A handle to the control whose action procedure you wish to change. 


actionProc A pointer to an action procedure defining what action your application 
takes while the user holds down the mouse button. 


The SetControlAction procedure changes the contrlAction field of the control’s 
control record to point to the action procedure specified in the act ionProc parameter. 
If the cursor is in the specified control, TrackCont rol calls this action procedure 
when user holds down the mouse button. You must provide the action procedure, and it 
must define some action to perform repeatedly as long as the user holds down the 
mouse button. (The TrackCont rol function always highlights and drags the control 
as appropriate.) 


SPECIAL CONSIDERATIONS 


SEE ALSO 


The value in the cont rlAction field of the control’s control record is used 
by TrackControl only if you set the action procedure to TrackControl to 
Pointer(-1). 


An action procedure is usually specified in a parameter to TrackControl; you 
generally don’t need to call Set Cont rolAction to change it. 


Action procedures are described in “Defining Your Own Action Procedures” beginning 
on page 5-115. 


Determining Control Values 


Your application sets a control’s various values—such as current setting, minimum and 
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maximum settings, title, reference value, and action procedure—when it creates the 
control. When the user clicks a control, however, your application often needs to 
determine the current setting and other possible values of that control. When the user 
clicks a checkbox, for example, your application must determine whether the box is 
checked before deciding whether to draw a checkmark inside the checkbox or remove 
the checkmark. 
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You can use the Get Cont rolValue, GetControlTitle, GetControlMinimum, 
GetControlMaximum, GetControlAction, and GetControlReference routines to 
determine, respectively, a control’s current setting, title, minimum setting, maximum 
setting, action procedure, and reference value. To get a handle to a control’s auxiliary 
control record, you can use the GetAuxiliaryControlRecord function; your 
application can use the acRefCon field of an auxiliary control record for any purpose. 
To determine the variation code that is specified in the control definition function for a 
particular control, you can use the Get ControlVariant function. This section also 
includes a description of the Set ControlReference procedure, which allows your 
application to change its reference value for a control. 


GetControl Value 


To determine a control’s current setting, use the Get Cont rolValue function. The 
GetControlValue function is also available as the Get Ct 1Value function. 


FUNCTION GetControlValue (theControl: ControlHandle): Integer; 


theControl A handle to a control. 


DESCRIPTION 
The Get Cont rolValue function returns as its function result the specified control’s 
current setting, which is stored in the contr1Value field of the control record. 


When you create a control, you specify an initial setting either in the control resource or 
in the value parameter of the NewCont rol function. You can change the setting by 
using the Set Cont rolValue procedure. 


SEE ALSO 


Listing 5-12 on page 5-37 and Listing 5-13 on page 5-38 illustrate the use of 
GetControlValue for determining the current setting of, respectively, a pop-up 
menu and a checkbox. Listing 5-16 on page 5-41, Listing 5-18 on page 5-53, and 
Listing 5-20 on page 5-61 illustrate the use of this function for determining the 
current setting of a scroll bar. 


GetControlMinimum 


To determine a control’s minimum setting, use the Get Cont rolMinimum function. The 
GetControlMinimum function is also available as the Get Ct 1Min function. 


FUNCTION GetControlMinimum (theControl: ControlHandle): Integer; 


theControl A handle to the control whose minimum value you wish to determine. 
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The Get Cont rolMinimum function returns as its function result the specified control’s 
minimum setting, which is stored in the cont r1Min field of the control record. 


When you create a control, you specify an initial minimum setting either in the control 
resource or in the min parameter of the NewCont rol function. You can change the 
minimum setting by using the Set Cont rolMinimum procedure. 


GetControlMaximum 


DESCRIPTION 


SEE ALSO 


To determine a control’s maximum setting, use the Get Cont rolMaximum function. The 
GetControlMaximum function is also available as the Get Ct 1Max function. 


FUNCTION GetControlMaximum (theControl: ControlHandle): Integer; 


theControl A handle to the control whose maximum value you wish to determine. 


The Get Cont rolMaximum function returns as its function result the specified control’s 
maximum setting, which is stored in the cont r1Max field of the control record. 


When you create a control, you specify an initial maximum setting either in the control 
resource or in the max parameter of the NewCont rol function. You can change the 
maximum setting by using the Set Cont rolMaximum procedure. 


Listing 5-16 on page 5-41 and Listing 5-20 on page 5-61 illustrate the use of 
GetControlMaximum for determining the maximum scrolling distance of a scroll bar. 


GetControlTitle 
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To determine the title of a control, use the Get Cont rolTitle procedure. The 
GetControlTitle procedure is also available as the Get CTitle procedure. 


PROCEDURE GetControlTitle (theControl: ControlHandle; 
VAR title: Str255); 


theControl A handle to the control whose title you want to determine. 
title The title of the control. 
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The GetControlTitle procedure returns the specified control title, which is stored in 


the contrlTitle field of the control record. 


When you create a control, you specify an initial title either in the control resource or in 
the title parameter of the NewCont rol function. You can change the title by using the 


SetControlTitle procedure. 


GetControlReference 


DESCRIPTION 


To determine a control’s current reference value, use the Get Cont rolReference 


function. The Get Cont rolReference function is also available as the Get CRefCon 


function. 


FUNCTION GetControlReference (theControl: ControlHandle): LongInt; 





theControl A handle to the control whose current reference value you wish 
to determine. 


The GetControlReference function returns as its function result the current reference 


value for the specified control. 


When you create a control, you specify an initial reference value, either in the control 
resource or in the refCon parameter of the NewCont rol function. The reference value 
is stored in the cont r1RfCon field of the control record. You can use this field for any 


purpose, and you can use the Set Cont rolReference procedure, described next, to 


change this value. 


SetControlReference 


To change a control’s current reference value, use the Set ControlReference 
procedure. The Set Cont rolReference procedure is also available as the 
SetCRefCon procedure. 





PROCEDURE SetControlReference (theControl: ControlHandle; 
data: LongInt); 


theControl A handle to the control whose reference value you wish to change. 


data The new reference value for the control. 
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DESCRIPTION 
The Set Cont rolReference procedure sets the control’s reference value to the value 
you specify in the data parameter. 


When you create a control, you specify an initial reference value, either in the 
control resource or in the refCon parameter of the NewCont rol function. The 
reference value is stored in the contr1RfCon field of the control record; you can 
use the Get ControlReference function to determine the current value. You 
can use this value for any purpose. 


GetControlAction 


To get a pointer to the action procedure stored in the cont rlAction field 
of the control’s control record, use the Get Cont rolAction function. The 
GetControlAction function is also available as the Get Ct lAct ion function. 


FUNCTION GetControlAction (theControl: ControlHandle): ProcPtr; 


theControl A handle to a control. 


DESCRIPTION 


The Get Cont rolAction function returns as its function result whatever value is 
stored in the contrlAction field of the control’s control record. This field specifies 
the action procedure that TrackCont rol uses if you set its act ionProc parameter to 
Pointer (-1). The action procedure should define an action to take in response to the 
user’s holding down the mouse button while the cursor is in the control. You can use 
the SetControlAction procedure to change this action procedure. 


SEE ALSO 


For information about defining an action procedure, see “Defining Your Own Action 
Procedures” beginning on page 5-115. 


GetControl Variant 


To determine the variation code specified in the control definition function for a 
particular control, you can use the GetControlVariant function. The 
GetControlVariant function is also available as the Get CVariant function. 


FUNCTION GetControlVariant (theControl: ControlHandle): Integer; 


theControl A handle to the control whose variation code you wish to determine. 
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The GetControlVariant function returns as its function result the variation code for 
the specified control. 


Variation codes are described in “The Control Definition Function” on page 5-14. 


GetAuxiliaryControlRecord 


DESCRIPTION 


Use the GetAuxiliaryControlRecord function to get a handle to a control’s 
auxiliary control record. The GetAuxiliaryControlRecord function is also 
available as the GetAuxCt1 function. 


FUNCTION GetAuxiliaryControlRecord (theControl: ControlHandle; 
VAR acHndl: AuxCtlHandle) 
Boolean; 


theControl A handle to a control. 


acHndl A handle to the auxiliary control record for the control. 


In its acHnd1 parameter, the GetAuxiliaryControlRecord function returns a 
handle to the auxiliary control record for the specified control. Your application typically 
doesn’t need to access an auxiliary control record unless you need its acRefCon field, 
which your application can use for any purpose. 


The value that GetAuxiliaryControlRecord returns for a function result depends 
on the control’s color control table, as described here: 


m If your application has changed the default control color table for the given control 
(either by using the Set Cont rolColor procedure or by creating its own control 
color table), the function returns TRUE. 


a If your application has not changed the default control color table, the function 
returns FALSE. 





m If you set the parameter theControl toNIL, the Dialog Manager ensures that 
the control uses the default color table, and GetAuxiliaryControlRecord 
returns TRUE. 
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Removing Controls 


When you use the Window Manager procedures Di sposeWindow and CloseWindow 


to remove a window, they automatically remove all controls associated with the window 
and release the memory the controls occupy. 


When you no longer need a control in a window that you want to keep, you can use the 
DisposeControl procedure to remove the control from the window’s control list and 
release the memory it occupies. You can use the Kil1 Controls procedure to dispose of 
all of a window’s controls at once. 


DisposeControl 


DESCRIPTION 


To remove a particular control from a window that you want to keep, use the 
DisposeControl procedure. 











PROCEDURE DisposeControl (theControl: ControlHandle) ; 





theControl A handle to the control you wish to remove. 


The DisposeControl procedure removes the specified control from the screen, deletes 
it from its window’s control list, and releases the memory occupied by the control record 
and any data structures associated with the control. 


SPECIAL CONSIDERATIONS 


The Window Manager procedures CloseWindow and DisposeWindow automatically 
dispose of all controls associated with the given window. 














SEE ALSO 
To remove all of the controls in a window, use the Kil1lControls procedure, described 
next. The CloseWindow and DisposeWindow procedures are described in the chapter 
“Window Manager” in this book. 

KillControls 
To remove all of the controls in a particular window that you want to keep, use the 
KillControls procedure. 
PROCEDURE KillControls (theWindow: WindowPtr); 
theWindow A pointer to the window containing the controls to remove. 
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The KillControls procedure disposes of all controls associated with the specified 
window by calling the DisposeCont rol procedure for each control. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


The Window Manager procedures CloseWindow and DisposeWindow automatically 
dispose of all controls associated with the given window. 


The CloseWindow and DisposeWindow procedures are described in the chapter 
“Window Manager” in this book. 


Application-Defined Routines 


This section describes how to create your own control definition function—declared 
here as MyCont rol—which your application needs to provide when defining new, 
nonstandard controls. This section also describes action procedures—declared here 

as MyAction and MyIndicatorAct ion—which define additional actions to be 
performed repeatedly as long as the user holds down the mouse button while the 
cursor is ina control. For example, you need to define an action procedure for scrolling 
through a document while the user holds down the mouse button and the cursor is 
ina scroll arrow. 


Defining Your Own Control Definition Function 


In addition to the standard controls (buttons, checkboxes, radio buttons, pop-up menus, 
and scroll bars), the Control Manager allows you to define new, nonstandard controls as 
appropriate for your application. For example, you can define a three-way selector 
switch, a memory-space indicator that looks like a thermometer, or a thruster control for 
a spacecraft simulator. Controls and their indicators may occupy regions of any shape, as 
permitted by QuickDraw. 


To define your own type of control, you write a control definition function, compile it as 
a resource of type 'CDEF', and store it in your resource file. (See the chapter “Resource 
Manager” in Inside Macintosh: More Macintosh Toolbox for more information about 
creating resources.) Whenever you create a control, you specify a control definition ID, 
which the Control Manager uses to determine the control definition function. The control 
definition ID is an integer that contains the resource ID of the control definition function 
in its upper 12 bits and a variation code in its lower 4 bits. Thus, for a given resource ID 
and variation code 


control definition ID = 16 x resource ID + variation code 


For example, buttons, checkboxes, and radio buttons all use the standard control 
definition function with resource ID 0. Because they have variation codes of 0, 1, 
and 2, respectively, their respective control definition IDs are 0, 1, and 2. 
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You can define your own variation codes, which various Control Manager routines pass 
to your control definition function. This allows you to use one 'CDEF'' resource to 
handle several variations of the same general control. 


The Control Manager calls the Resource Manager to access your control definition 
function with the given resource ID. The Resource Manager reads your control definition 
function into memory and returns a handle to it. The Control Manager stores this handle 
in the contr1lDefProc field of the control record. In 24-bit addressing mode, the 
variation code is placed in the high-order byte of this field; in 32-bit mode, the variation 
code is placed in the most significant byte of the acReserved field in the control’s 
AuxCt1Rec record. Later, when various Control Manager routines need to perform a 
type-dependent action on the control, they call your control definition function and pass 
it the variation code as a parameter. 


If you create a control definition function, you can use control color table records of 
any desired size and define their contents in any way you wish, except that part indices 
1 through 127 are reserved for system definition. Note that in this case, you should 
allocate explicit auxiliary records for every control you create. 


If you wish to define new, nonstandard controls for your application, you must write a 
control definition function and store it in a resource file as a resource of type 'CDEF'. 
Here’s how you would declare a procedure named MyCont rol: 


FUNCTION MyControl (varCode: Integer; theControl: ControlHandle; 
message: Integer; param: LongInt): LongInt; 





varCode The variation code for this control. To derive the control definition ID for 
the control, add this value to the result of 16 multiplied by the resource ID 
of the 'CDEF'' resource containing this function. The variation code 
allows you to specify several control definition IDs within one 'CDEF' 
resource, thereby defining several variations of the same basic control. 





theControl A handle to the control that the operation will affect. 


message A value (from the following list) that specifies which operation your 
function must undertake. 


CONST drawCntl = 0; {draw the control or its part} 
testCntl = 1; {test where mouse button } 
{ is pressed} 
calcCRgns = 2% {calculate region for } 
{ control or indicator in } 
{ 24-bit systems} 


initCntl {peform any additional } 


ll 
Ww 
~ 


{ control initialization} 
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dispCntl = 4; {perform any additional } 

{ disposal actions} 
posCntl =5% {move indicator and } 

{ update its setting} 
thumbCntl = 6; {calculate parameters for } 

{ dragging indicator} 
dragCntl = 7; {perform any custom dragging } 

{ of control or its indicator} 
autoTrack = 8; {execute action procedure } 

{ specified by your function} 
calcCntlRgn = 10; {calculate region for control} 
calcThumbRgn = 11; {calculate region for } 

{ indicator} 

param A value whose meaning depends on the operation specified in the 


message parameter. 


The Control Manager calls your control definition function under various circumstances; 
the Control Manager uses the message parameter to inform your control definition 
function what action it must perform. The data that the Control Manager passes in the 
param parameter, the action that your control definition function must undertake, and 
the function result that your control definition function returns all depend on the value 
that the Control Manager passes in the message parameter. The rest of this section 
describes how to respond to the various values that the Control Manager passes in the 
message parameter. 


Drawing the Control or Its Part 


When the Control Manager passes the value for the drawCnt1 constant in the message 
parameter, the low word in the param parameter has one of the following values: 


m the value 0, indicating the entire control 
m the value 129, signifying an indicator that must be moved 


m any other value, indicating a part code for the control (Don’t use part code 128, which 
is reserved for future use, or part code 129, which the Control Manager uses to signify 
an indicator that must be moved.) 


Note 

For the drawCnt1 message, the high-order word of the param 
parameter may contain undefined data; therefore, evaluate only 
the low-order word of this parameter. @ 


If the specified control is visible, your control definition function should draw the control 
(or the part specified in the param parameter) within the control’s rectangle. If the 
control is invisible (that is, if its contr1Vis field is set to 0), your control definition 
function does nothing. 


Control Manager Reference 5-111 


5-112 


CHAPTER 5 


Control Manager 


When drawing the control or its part, take into account the current values of its 
contrlHilite and contrlValue fields of the control’s control record. 


If the part code for your control’s indicator is passed in param, assume that the indicator 
hasn’t moved; the Control Manager, for example, may be calling your control definition 
function so that you may simply highlight the indicator. However, when your applica- 
tion calls the SetControlValue, SetControlMinimum, and SetControlMaximum 
procedures, they in turn may call your control definition function to redraw the 
indicator. Since these routines have no way of determining what part code you chose 

for your indicator, they all pass 129 in param, meaning that you should move your 
indicator. Your control definition function must detect this part code as a special case and 
remove the indicator from its former location before drawing it. If your control has more 
than one indicator, you should interpret 129 to mean all indicators. 


When passed the value for the drawCnt1 constant in the message parameter, your 
control definition function should always return 0 as its function result. 


Testing Where the Mouse-Down Event Occurs 


To request your control definition function to determine whether a specified point is 

in a visible control, the FindControl function sends the value for the testCnt1 
constant in the message parameter. In this case, the param parameter specifies a point 
(in coordinates local to the control’s window) as follows: 


ma The point’s vertical coordinate is contained in the high-order word of the long integer. 


m The point’s horizontal coordinate is contained in the low-order word. 


When passed the value for the testCnt1 constant in the message parameter, your 
control definition function should return the part code of the part that contains the 
specified point; it should return 0 if the point is outside the control or if the control 

is inactive. 


Calculating the Control and Indicator Regions 


When the Control Manager passes the value for the calcCRgns constant in the 
message parameter, your control definition function should calculate the region 
occupied by either the control or its indicator. The Control Manager passes a QuickDraw 
region handle in the param parameter; it is this region that you calculate. If the 
high-order bit of param is set, the region requested is that of the control’s indicator; 
otherwise, the region requested is that of the entire control. Your control definition 
function should clear the high bit of the region handle before calculating the region. 


When the Control Manager passes the value for the calcCnt1Rgn constant in the 
message parameter, your control definition function should calculate the region passed 
in the param parameter for the specified control. When the Control Manager passes the 
value for the calcThumbRgn constant, calculate the region occupied by the indicator. 


When passed the values for the calcCRgns, calcCnt1Rgn, and calcThumbRgn 
constants, your control definition function should always return 0, and it should express 
the region in the local coordinate system of the control’s window. 
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IMPORTANT 

The Control Manager passes the calcCRgns constant when the 24-bit 
Memory Manager is in operation. When the 32-bit Memory Manager is 
in operation, the Control Manager instead passes the calcCnt1Rgn 
constant or the calcThumbRgn constant. Your control definition 
function should respond to all three constants. A 


Performing Any Additional Initialization 


After initializing fields of a control record as appropriate when creating a new control, 
the Control Manager passes initCnt1 in the message parameter to give your control 
definition function the opportunity to perform any type-specific initialization you may 
require. For example, if you implement the control’s action procedure in its control 
definition function, you'll need to store Pointer (-1) inthe contrlAction field of the 
control’s control record. Then, in a call to TrackCont rol for this control, you would 
pass Pointer (-1) inthe actionProc parameter of TrackControl. 


The standard control definition function for scroll bars allocates space for a region to 
hold the scroll box and stores the region handle in the cont r1Data field of the new 
control record. 


When passed the value for the initCnt1 constant in the message parameter, your 
control definition function should ignore the param parameter and return 0 as a 
function result. 


Performing Any Additional Disposal Actions 


The DisposeCont rol procedure passes dispCnt1 in the message parameter to give 
your control definition function the opportunity to carry out any additional actions 
when disposing of a control. For example, the standard definition function for scroll bars 
releases the memory occupied by the scroll box region, whose handle is kept in the 
contr1Data field of the control’s control record. 


When passed the value for the dispCnt1 constant in the message parameter, your 
control definition function should ignore the param parameter and return 0 as a 
function result. 


Moving the Indicator 


When a mouse-up event occurs in the indicator of a control, the TrackControl 
function calls your control definition function and passes posCnt1 in the message 
parameter. In this case, the param parameter contains a point (in coordinates local to the 
control’s window) that specifies the vertical and horizontal offset, in pixels, by which 
your control definition function should move the indicator from its current position. 
Typically, this is the offset between the points where the cursor was when the user 
pressed and released the mouse button while dragging the indicator. The offset point is 
specified as follows: 


a The point’s vertical offset is contained in the high-order word of the param parameter. 


a The point’s horizontal offset is contained in the low-order word. 
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Your definition function should calculate the control’s new setting based on the 
given offset and then, to reflect the new setting, redraw the control and update the 
contrlValue field in the control’s control record. Your control definition function 
should ignore the param parameter and return 0 as a function result. 


Note that the SetControlValue, SetControlMinimum, and SetControlMaximum 
procedures do not call your control definition function with the posCnt 1 message; 
instead, they pass the drawCnt1 message. 


Calculating Parameters for Dragging the Indicator 


When the Control Manager passes the value for thumbCnt 1 in the message parameter, 
your control definition function should respond by calculating values (analogous to 

the limitRect, slopRect, and axis parameters of DragCont rol) that constrain 
how the indicator is dragged. The param parameter contains a pointer to the following 
data structure: 





RECORD 
limitRect,slopRect: Rect; 
axis: Integer; 
END; 


On entry, the field param*.limitRect .topLeft contains the point where the 
mouse-down event first occurred. Your definition function should store the appropriate 
values into the fields of the record pointed to by param; they’re analogous to the 
similarly named parameters to the Window Manager function DragGrayRgn. 


Performing Custom Dragging 


The Control Manager passes dragCnt1 in the message parameter to give your control 
definition function the opportunity to specify its own method for dragging a control (or 
its indicator). 


The param parameter specifies whether the user is dragging an indicator or the 
whole control: 


m A value of 0 means the user is dragging the entire control. 
m Any nonzero value means the user is dragging only the indicator. 


If you want to use the Control Manager’s default method of dragging (which is to call 
DragControl to drag the control or the Window Manager function DragGrayRgn to 
drag its indicator), return 0 as the function result for your control definition function. 


If your control definition function returns any nonzero result, the Control Manager does 
not drag your control, and instead your control definition function must drag the 
specified control (or its indicator) to follow the cursor until the user releases the mouse 
button, as follows: 


m Ifthe user drags the entire control, your definition function should use the 
MoveCont rol procedure to reposition the control to its new location after the user 
releases the mouse button. 
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m Ifthe user drags the indicator, your definition function must calculate the control’s 
new setting (based on the pixel offset between the points where the cursor was when 
the user pressed and released the mouse button while dragging the indicator) and 
then, to reflect the new setting, redraw the control and update the contr1lValue field 
in the control’s control record. Note that, in this case, the TrackControl function 
returns 0 whether or not the user changes the indicator’s position. Thus, you must 
determine whether the user has changed the control's setting, for instance, by 
comparing the control’s value before and after the call to TrackControl. 


Executing an Action Procedure 


You can design a control whose action procedure is specified by your control definition 
function. When you create the control, your control definition function must first 
respond to the initCnt1 message by storing Pointer (-1) inthe contrlAction 
field of the control’s control record. (As previously explained, the Control Manager 
sends the initCnt1 message to your control definition function after initializing 

the fields of a new control record.) Then, when your application passes Pointer (-1) 
in the actionProc parameter to the TrackControl function, TrackControl 

calls your control definition function with the autoTrack message. The param 
parameter specifies the part code of the part where the mouse-down event occurs. 
Your control definition function should then use this information to respond as an action 
procedure would. 


Note 


For the autoTrack message, the high-order word of the param 
parameter may contain undefined data; therefore, evaluate only 
the low-order word of this parameter. @ 


ASSEMBLY-LANGUAGE INFORMATION 


The function’s entry point must be at the beginning. 


SEE ALSO 


The TrackControl function is described on page 5-90; creating an action procedure is 
described in the next section. 


Defining Your Own Action Procedures 


When a mouse-down event occurs in a control, the TrackCont rol function responds as 
appropriate by highlighting the control or dragging the indicator as long as the user 
holds down the mouse button. You can define other actions to be performed repeatedly 
during this interval. To do so, define your own action procedure and point to it in the 
actionProc parameter of the TrackControl function. 


When calling your action procedure for a control part other than an indicator, 
TrackControl passes your action procedure (1) a handle to the control and (2) the 
control’s part code. Your action procedure should then respond as appropriate. For 
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example, if the user is working in a text document and holds down the mouse button 
while the cursor is in the lower scroll arrow, your application should scroll continuously 
one line at a time until the user releases the mouse button or reaches the end of 

the document. 


For a control part other than an indicator, you declare an action procedure that takes two 
parameters: a handle to the control in which the mouse-down event occurred and an 
integer that represents the part of the control in which the mouse-down event occurred. 
Such an action procedure is declared as MyAct ion in the following section. 


If the mouse-down event occurs in an indicator, your action procedure should take no 
parameters, because the user may move the cursor outside the indicator while dragging 
it. Such an action procedure, declared here as MyIndicatorAction, is described on 
page 5-117. 


Because it will be called with either zero or two parameters, according to whether the 
mouse-down event occurred in an indicator or elsewhere, your action procedure can be 
defined for only one case or the other. The only way to specify actions in response to all 
mouse-down events in a control, regardless of whether they’re in an indicator, is to 
define your own control definition function, as described in “Defining Your Own Control 
Definition Function” beginning on page 5-109. 


Here’s how to declare an action procedure for a control part other than an indicator if 
you were to name the procedure MyAction: 














PROCEDURE MyAction (theControl: ControlHandle; partCode: Integer); 


theControl A handle to the control in which the mouse-down event occurred. 


partCode When the cursor is still in the control part where mouse-down event first 
occurred, this parameter contains that control’s part code. When the 
user drags the cursor outside the original control part, this parameter 
contains 0. 


Your procedure can perform any action appropriate for the control part. For example, 
when a mouse-down event occurs in a scroll arrow or gray area of a scroll bar, 
TrackControl calls your action procedure and passes it the part code and a handle 
to the scroll bar. Your action procedure should examine the part code to determine 
the part of the control in which the mouse-down event occurred. Your action 
procedure should then scroll up or down a line or page as appropriate and then call 
the SetControlValue procedure to change the control’s setting and redraw the 
scroll box. 
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ASSEMBLY-LANGUAGE INFORMATION 


If you store a pointer to a procedure in the global variable DragHook, your procedure is 
called repeatedly (with no parameters) as long as the user holds down the mouse button. 
The TrackCont rol function invokes the Window Manager function DragGrayRgn, 
which calls the DragHook procedure. The DragGrayRgn function uses the pattern 
stored in the global variable DragPattern for the dragged outline of the indicator. 


SEE ALSO 
Listing 5-19 on page 5-59 illustrates a pair of action procedures for scrolling through a 
text document. As an alternative to passing a pointer to your action procedure in a 
parameter to TrackControl, you can use the Set Cont rolAction procedure to 
store a pointer to the action procedure in the cont rlAction field in the control record. 
When you pass Pointer (-1) instead of a procedure pointer to TrackControl, 
TrackControl uses the action procedure pointed to in the control record. 


MyIndicatorAction 


Here’s how to declare an action procedure for an indicator if you were to name the 
procedure MyIndicatorAction: 


PROCEDURE MyIndicatorAction; 





DESCRIPTION 
Your procedure can perform any action appropriate for the control part. For example, if 
your application plays music while displaying a volume control slider, your application 
should change the volume in response to the user’s action in the slider switch. 


SEE ALSO 
See the MyAction procedure described on page 5-116 for other considerations. 


Resources 


This section describes the control ('CNTL") resource and the control color table 
('cctb") resource. You can use the control resource to define a control and use the 
control color table resource to change the default colors of a control’s parts. 
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You can use a control resource to define a control. A control resource is a resource of 
type 'CNTL'. All control resources must have resource ID numbers greater than 128. 

Use the Get NewCont rol function (described on page 5-81) to create a control defined in 
a control resource. The Control Manager uses the information you specify to create a 
control record in memory. (The control record is described on page 5-73.) 


This section describes the structure of this resource after it is compiled by the Rez 
resource compiler, available from APDA. The format of a Rez input file for a control 
resource differs from its compiled output form, which is illustrated in Figure 5-25. If you 
are concerned only with creating a control resource, see “Creating and Displaying a 
Control” beginning on page 5-15. 


Figure 5-25 Structure of a compiled control ('CNTL"') resource 
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The compiled version of a control resource contains the following elements: 


mu The rectangle, specified in coordinates local to the window, that encloses the control; 
this rectangle encloses the control and thus determines its size and location. 
m The initial setting for the control. 
For controls—such as buttons—that don’t retain a setting, this value should be 0. 


For controls—such as checkboxes or radio buttons—that retain an on-or-off setting, 
a value of 0 in this element indicates that the control is initially off; a value of 1 
indicates that the control is initially on. 


For controls—such as scroll bars and dials—that can take a range of settings, 
whatever initial value is appropriate within that range is specified in this element. 
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For pop-up menus, a combination of values instructs the Control Manager where 
and how to draw the control title. Appropriate values, along with the constants 
used to specify them in a Rez input file, are listed here: 











CONST popupTitleBold = $00000100; {boldface font style} 
popupTitlelItalic = $00000200; {italic font style} 
popupTitleUnderline = $00000400; {underline font } 

{ style} 
popupTitleOutline = $00000800; {outline font style} 
popupTitleShadow = $00001000; {shadow font style} 
popupTitleCondense = $00002000; {condensed text} 
popupTitleExtend = $00004000; {extended text} 
popupTitleNoStyle = $00008000; {monostyle text} 
popupTitleLeftJust = $00000000; {place title left } 


{ of pop-up box} 
$00000001; {center title over } 
{ pop-up box} 
SOOOOOOFF; {place title right } 
{ of pop-up box} 


popupTitleCenterJust 


popupTitleRightJust 





a The visibility of the control. If this element contains the value TRUE, GetNewCont rol 
draws the control immediately, without using the application’s standard updating 
mechanism for windows. If this element contains the value FALSE, the application 
must use the ShowCont rol procedure (described on page 5-86) when it’s prepared to 
display the control. 


mg Fill. This should be set to 0. 


a The maximum setting for the control. 
For controls—such as buttons—that don’t retain a setting, this value should be 1. 


For controls—such as checkboxes or radio buttons—that retain an on-or-off setting, 
this element should contain the value 1 (meaning “on”). 

For controls—such as scroll bars and dials—that can take a range of settings, this 
element can contain whatever maximum value is appropriate; when the 
application makes the maximum setting of a scroll bar equal to its minimum 
setting, the control definition function automatically makes the scroll bar inactive, 
and when the application makes the maximum setting exceed the minimum, the 
control definition function makes the scroll bar active again. 


For pop-up menus, this element contains the width, in pixels, of the control title. 


a The minimum setting for the control. 
For controls—such as buttons—that don’t retain a setting, this value should be 0. 


For controls—such as checkboxes or radio buttons—that retain an on-or-off setting, 
the value 0 (meaning “off”) should be set in this element. 


For controls—such as scroll bars and dials—that can take a range of settings, this 
element contains whatever minimum value is appropriate. 


For pop-up menus, this element contains the resource ID of the 'MENU' resource 
that describes the menu items. 
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a The control definition ID, which the Control Manager uses to determine the control 
definition function for this control. “Defining Your Own Control Definition Function” 
beginning on page 5-109 describes how to create control definition functions and their 
corresponding control definition IDs. The following list shows the control definition 
ID numbers—and the constants that represent them in Rez input files—for the 
standard controls. 








CONST 
pushButProc = 0; {button} 
checkBoxProc = 1; {checkbox} 
radioButProc = 2; {radio button} 
useWFont = 8; {when added to above, shows } 
{ title in the window font} 
scrollBarProc = 16; {scroll bar} 
popupMenuProc = 1008; {pop-up menu} 
popupFixedWidth = $0001; {add to popupMenuProc to } 
{ use fixed-width control} 
popupUseAddResMenu = $0004; {add to popupMenuProc to } 
{ specify a value of type } 
{ ResType in the contrlRfCon } 
{ field of the control } 
{ record; Menu Manager } 
{ adds resources of this } 
{ type to the menu} 
popupUseWFont = $0008; {if added to popupMenuProc, } 
{ shows title in window font} 
Note 


The title of a button, checkbox, radio button, or pop-up menu normally 
appears in the system font, which in Roman script systems is 12-point 
Chicago. Do not use a smaller font; some script systems, such as 
KanjiTalk, require 12-point fonts. You should generally use the system 
font in your controls; doing so will simplify localization effort. However, 
if you absolutely need to display a control title in the font currently 
associated with the window’s graphics port, you can add the 
popupUseWF ont constant to the pop-up menu control definition 

ID or add the useWFont constant to the other standard control 
definition IDs. 


a The control’s reference value, which is set and used only by the application (except 
when the application adds the popupUseAddResMenu variation code to the 
popupMenuProc control definition ID, as described in “Creating a Pop-Up Menu” 
beginning on page 5-25). 
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m For controls—such as buttons, checkboxes, radio buttons, and pop-up menus—that 
need a title, the string for that title; for controls that don’t use titles, an empty string. 


After you use GetNewCont rol to create the control, you can change the current setting, 
the maximum setting, the minimum setting, the reference value, and the title by using, 
respectively, the SetControlValue, SetControlMaximum, SetControlMinimum, 
SetControlReference, and SetControlTitle routines. You can use the 
MoveControl and SizeCont rol procedures to change the control’s rectangle. You 

can use the Get Cont rolValue, GetControlMaximum, GetControlMinimun, 
GetControlReference, and GetControlTitle routines to determine the 

control values. 


The Control Color Table Resource 


On color monitors, the Control Manager automatically draws control parts so that they 
match the colors of the controls used by system software. 


If you feel absolutely compelled to use nonstandard colors, the Control Manager 

allows you to do so. Your application can specify these by creating a control color table 
('cctb") resource; you must give the control color table resource for a control the 

same resource ID as its control ('CNTL') resource, which is described on page 5-118. 
When you call the GetNewCont rol function to create the control, the Control Manager 
automatically attempts to load a control color table resource with the same resource ID 
as the control resource specified to Get NewCont rol. The Control Manager also creates 
an auxiliary control record for the control; the auxiliary control record is described 

on page 5-76. 


Note 


Using nonstandard colors in your controls may initially confuse 
your users. 


Generally, you use a control color table resource for a control that you define in a control 
resource. To change a control's colors, or to use nonstandard colors in a control 

you create using NewCont rol, create a control color table record and use the 
SetControlColor procedure. The control color table record is described on page 5-77; 
the SetControlColor procedure is described on page 5-101. 


A control color table resource is of type 'cctb'. All control color table resources must 
have resource ID numbers greater than 128. Figure 5-26 on the next page shows the 
format of a control color table resource. Note that DisposeControl does not delete 
a control color table resource; therefore, you should make each control color table 
resource purgeable. 
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Figure 5-26 Structure of a compiled control color table ('cctb") resource 
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You define a control color table resource by specifying these elements in a resource with 
the 'cctb' resource type: 


m Reserved. Should always be set to 0. 
m Reserved. Should always be set to 0. 


= Number of control parts. For standard controls other than scroll bars, this should be 
set to 3, because these controls consist of a frame, a control body, and text. For scroll 
bars, this should be set to 12. A scroll bar consists of a frame, a body, and scroll box; 
each part of a scroll bar has various highlight and tinge colors associated with it. To 
create a control with more parts, you must create your own control definition function 
(as described in “Defining Your Own Control Definition Function” beginning on 
page 5-109) that recognizes additional parts. 


a First part identifier. A value or constant that identifies the control’s part to color. The 
part identifiers can be listed in any order. The scroll bar control definition function 
may use more than one part identifier to produce the actual colors used for each part 
of the scroll bar. 





CONST 
cFrameColor = 0; {frame color; for scroll bars, used to produce } 
{ foreground color for scroll arrows & gray area} 
cBodyColor = 1; {body color; for scroll bars, used to produce } 
{ colors in the scroll box} 
cTextColor = 25 {text color; unused for scroll bars} 
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cArrowsColorLight = 5; {Used to produce colors in arrows & scroll bar } 
{ background color} 
cArrowsColorDark = 6; {Used to produce colors in arrows & scroll bar } 
{ background color} 
cThumbLight = 7; {Used to produce colors in scroll box} 
cThumbDark = 8; {Used to produce colors in scroll box} 
cHiliteLight = 9; {Use same value as wHiliteColorLight in 'wctb'} 
cHiliteDark = 10; {Use same value as wHiliteColorDark in 'wctb'} 
cTitleBarLight = 11; {Use same value as wTitleBarLight in 'wctb'} 
cTitleBarDark = 12; {Use same value as wTitleBarDark in 'wctb'} 
cTingeLight = 13; {Use same value as wTingeLight in 'wctb'} 
cTingeDark = 14; {Use same value as wTingeDark in 'wctb'} 


m= Red component. An integer that represents the intensity of the red component of 
the color to use when drawing this part of the control. In this and the next two 
elements, use 16-bit unsigned integers to give the intensity values of three additive 


primary colors. 


m Green component. An integer that represents the intensity of the green component of 
the color to use when drawing this part of the control. 


m Blue component. An integer that represents the intensity of the blue component of the 
color to use when drawing this part of the control. 


m Part identifier and red, green, and blue components for the next control part. You can 
list parts in any order in this resource. If the application specifies a part identifier that 
cannot be found, the Control Manager uses the colors for the control’s first identifiable 
part. If a part is not listed in the control color table, the Dialog Manager draws it in its 


default color. 


The Control Definition Function 


The resource type for a control definition function is 'CDEF'. The resource data is 
the compiled or assembled code of the function. See “Defining Your Own Control 
Definition Function” beginning on page 5-109 for information about creating a control 


definition function. 


Control Manager Reference 


5-123 


CHAPTER 5 


Control Manager 


Summary of the Control Manager 


Pascal Summary 








Constants 
CONST 
{control definition IDs} 
pushButProc = 0; {button} 
checkBoxProc =A; {checkbox} 
radioButProc = 2; {radio button} 
useWFont = 8; {add to above to display control title in } 
{ the window font} 
scrollBarProc = 16; {scroll bar} 
popupMenuProc = 1008; {pop-up menu} 
popupMenuCDEFproc = popupMenuProc; {synonym for compatibility} 


{pop-up menu CDEF variation codes} 





popupFixedWidth = $0001; {add to popupMenuProc to use } 
{ fixed-width control} 
popupUseAddResMenu = $0004; {add to popupMenuProc to specify a } 


{ value of type ResType in the } 

{ contrlRfCon field of the control } 

{ record; Menu Manager adds } 

{ resources of this type to the menu} 
popupUseWFont = $0008; {add to popupMenuProc to show control } 

{ title in the window font} 


{part codes} 


inButton = 10; {button} 
inCheckBox = AAs {checkbox or radio button} 
inUpButton = 20; {up arrow for a vertical scroll bar, } 


{ left arrow for a horizontal scroll bar} 





inDownButton = 21; {down arrow for a vertical scroll bar, } 

{ right arrow for a horizontal scroll bar} 
inPageUp = 22; {gray area above scroll box for a } 

{ vertical scroll bar, gray area to } 

{ left of scroll box for a horizontal } 

{ scroll bar} 
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inPageDown 


inThumb 


23; {gray area below scroll box for a } 


{ vertical scroll bar, gray area to } 


{ right of scroll box for a horizontal } 


{ scroll bar} 


129; {scroll box (or other indicator) } 


{pop-up title characteristics} 


popupTitleBold 
popupTitlelItalic 
popupTitleUnderline 
popupTitleOutline 
popupTitleShadow 
popupTitleCondense 
popupTitleExtend 
popupTitleNoStyle 
popupTitleLeftJust 
popupTitleCenterJust 
popupTitleRightJust 


$00000100; 
$00000200; 
$00000400; 
$00000800; 
$00001000; 
$00002000; 
$00004000; 
$00008000; 
$00000000; 
$00000001; 
SOOOOQOOFF; 


{boldface font style} 

{italic font style} 

{underline font style} 

{outline font style} 

{shadow font style} 

{condensed characters} 

{extended characters} 
{monostyled text} 

{place title left of pop-up box} 
{center title over pop-up box} 
{place title right of pop-up box} 


{axis constraints for DragControl procedure} 


noConstraint 
hAxisOnly 
vAxisOnly 


= 0; {no constraint} 
1; {drag along horizontal axis only} 
2; {drag along vertical axis only} 


{constants for the message parameter in a control definition function} 


drawCntl 
testCntl 
calcCRgns 


initCntl 
dispCntl 
poscCntl 
thumbCntl 
dragCntl 


autoTrack 


calcCntlRgn 
calcThumbRgn 


{part identifiers for ColorSpec records ina 


cFrameColor 


0; {draw the control or its part} 
dy {test where mouse button is pressed} 
2; {calculate region for control or indicator in } 


{ 24-bit systems} 


; {peform any additional control initialization} 


; {take any additional disposal actions} 


; {calculate parameters for dragging indicator} 


3 
4 
5; {move indicator and update its setting} 
6 
7 


; {perform any custom dragging of control or } 


{ its indicator} 


8; {execute action procedure specified by your } 


{ function} 


10; {calculate region for control} 


11; {calculate region for indicator} 


0; {frame color; for scroll bars, also fore- } 


control color table resource} 


{ ground color for scroll arrows and gray area} 
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cBodyColor = 1; {for scroll bars, background color for } 
{ scroll arrows and gray area; for other } 
{ controls, the fill color for body of control} 
cTextColor = 2; {text color; unused for scroll bars} 
cThumbColor = 3; {Reserved} 
Data Types 
TYPE ControlPtr = *ControlRecord; 
ControlHandle = *“ControlPtr; 
ControlRecord = 
PACKED RECORD 
nextControl: ControlHandle; {next control} 
contrlOwner: WindowPtr; {control's window} 
contrlRect: Rect; {rectangle} 
contrlVis: Byte; {255 if visible} 
contrlHilite: Byte; {highlight state} 
contrlValue: Integer; {control's current setting} 
contrl1Min: Integer; {control's minimum setting} 
contr1Max: Integer; {control's maximum setting} 
contrlDefProc: Handle; {control definition function} 
contrlData: Handle; {data used by contrlDefProc} 
contrlAction: ProcPtr; {action procedure} 
contrlRfCon: LongInt; {control's reference value} 
contrlTitle: Str255; {control's title} 
END; 
AuxCt1lPtr = *AuxCtlRec; 
AuxCtlHandle = *AuxCtlPtr; 
AuxCtlRec = 
RECORD 
acNext: AuxCtlHandle; {handle to next AuxCtlRec} 
acOwner: ControlHandle; {handle to this record's control} 
acCTable: CCTabHandle; {handle to color table record} 
acFlags: Integer; {reserved} 
acReserved: LongInt; {reserved for future use} 
acRefCon: LongInt; {for use by application} 
END; 
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CCTabPtr = *CtlCTab; 
CCTabHandle = *“CCTabPtr; 
CtlcTab = 
RECORD 
ccSeed: LongInt; {reserved; set to 0} 
ccRider: Integer; {reserved; set to 0} 
ctSize: Integer; {number of ColorSpec records in next } 
{ field; 3 for standard controls} 
ctTable: ARRAY[0..3] OF ColorSpec; 
END; 
Control Manager Routines 
Creating Controls 
FUNCTION GetNewControl (controlID: Integer; owner: WindowPtr) 
ControlHandle; 
FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; 


title: Str255; visible: Boolean; 

value: Integer; min: Integer; max: Integer; 

procID: Integer; refCon: LongInt) 
ControlHandle; 


Drawing Controls 


{UpdateControls is also spelled as UpdtControl} 





PROCEDURE ShowControl (theControl: ControlHandle) ; 

PROCEDURE UpdateControls (theWindow: WindowPtr; updateRgn: RgnHandle) ; 
PROCEDURE DrawControls (theWindow: WindowPtr); 

PROCEDURE DrawlControl (theControl: ControlHandle) ; 











Handling Mouse Events in Controls 


FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; 
VAR theControl: ControlHandle): Integer; 
FUNCTION TrackControl (theControl: ControlHandle; thePoint: Point; 
actionProc: ProcPtr): Integer; 
FUNCTION TestControl (theControl: ControlHandle; thePt: Point) 
Integer; 
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Changing Control Settings and Display 


{some routines have 2 spellings——see Table 5-1 for the alternate spellings} 


PROCEDURE SetControlValue (theControl: 
PROC] 


Gl 





DURE SetControlMinimum (theControl: 
PROCEDURE SetControlMaximum (theControl: 




















ControlHandle; 
ControlHandle; 
ControlHandle; 


ControlHandle; 


ControlHandle) ; 


ControlHandle; 
7 


ControlHandle; 


ControlHandle; 


hiliteState: Integer); 








ControlHandle; 
Rect; slopRect: 


ControlHandle; 


PROCEDURE SetControlTitle (theControl: 
PROCEDURE HideControl (theControl: 
PROCEDURE MoveControl (theControl: 
v: Integer) 
PROCEDURE SizeControl (theControl: 
Integer) ; 
PROCEDURE HiliteControl (theControl: 
PROCEDURE DragControl (theControl: 
limitRect: 
axis: Integer); 
PROCEDURE SetControlColor (theControl: 
CCTabHandle) ; 


PROCEDURE SetControlAction (theControl: 
actionProc: 


Determining Control Values 


ControlHandle; 
ProcPtr); 


theValue: Integer); 
minValue: Integer); 
maxValue: Integer); 


title: Str255); 


h: Integer; 


w: Integer; h: 


startPt: Point; 
Rect; 


newColorTable: 


{some routines have 2 spellings——see Table 5-1 for the alternate spellings} 


FUNCTION GetControlValue (theControl: 
FUNCTION GetControlMinimum (theControl: 
FUNCTION GetControlMaximum (theControl: 
PROCEDURE GetControlTitle (theControl: 


FUNCTION GetControlReference 
(theControl: 


PROCEDURE SetControlReference 
(theControl: 


FUNCTION GetControlAction (theControl: 
FUNCTION GetControlVariant (theControl: 


FUNCTION GetAuxiliaryControlRecord 
(theControl: 
VAR acHndl: 


Removing Controls 


PROCEDURE DisposeControl (theControl: 
PROCEDURE KillControls (theWindow: 
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ControlHandle): 
ControlHandle): 


ControlHandle): 


ControlHandle; 


ControlHandle): 


ControlHandle; 


ControlHandle): 


andle): 


Control 








ControlHandle; 
AuxCtlHandle): 


ControlHandle) ; 
WindowPtr) ; 


Integer; 
Integer; 
Integer; 


VAR title: Str255); 


LongInt; 


data: LongInt); 
ProcPtr; 


Integer; 


Boolean; 
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Application-Defined Routines 


Defining Your Own Control Definition Function 





FUNCTION MyControl (varCode: Integer; theControl: ControlHandle; 
message: Integer; param: LongInt) : LongInt; 





Defining Your Own Action Procedures 





PROCEDURE MyAction (theControl: ControlHandle; partCode: Integer) ; 











PROCEDURE MyIndicatorAction; 








C Summary 
Constants 
enum { 
/*control definition IDs*/ 
pushButProc = 0; /*button* / 
checkBoxProc =o /*checkbox*/ 
radioButProc = 2; /*radio button*/ 
useWFont = 8, /*add to above to display control */ 
/* title in the window font*/ 
scrollBarProc = 16, /*scroll bar*/ 
popupMenuProc = 1008, /*pop-up menu*/ 





/*pop-up menu CDEF variation codes*/ 
popupFixedWidth = 1 << 0, /*add to popupMenuProc to use */ 
/* use fixed-width control*/ 


popupUseAddResMenu = 1 << 2, /*add to popupMenuProc to specify a */ 





/* value of type ResType in the */ 
/* contriRfCon field of the control */ 
/* record; Menu Manager adds */ 
/* resources of this type to the menu*/ 
popupUseWFont = 1 << 3 /*add to popupMenuProc to display */ 
/* control title in the window font*/ 
}; 
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enum { 


/*part codes*/ 


inButton = 10, /*button*/ 
inCheckBox = 11, /*checkbox or radio button*/ 
inUpButton = 20, /*up arrow for a vertical scroll bar, */ 


/* left arrow for a horizontal scroll bar*/ 
inDownButton = 21, /*down arrow for a vertical scroll bar, */ 
/* right arrow for a horizontal scroll bar*/ 
inPageUp = 22, /*gray area above scroll box for a */ 
/* vertical scroll bar, gray area to */ 
/* left of scroll box for a horizontal */ 
/* scroll bar*/ 
inPageDown = 23, /*gray area below scroll box for a */ 
/* vertical scroll bar, gray area to */ 
/* right of scroll box for a horizontal */ 
/* scroll bar*/ 
inThumb = 129 /*scroll box (or other indicator) */ 
}; 


enum { 


/*pop-up title characteristics*/ 


popupTitleBold = 1 << 8, /*boldface font style*/ 
popupTitleItalic =1 << 9, /*italic font style*/ 
popupTitleUnderline = 1 << 10, /*underline font style*/ 
popupTitleOutline = 1 << 11, /*outline font style*/ 
popupTitleShadow = 1 << 12, /*shadow font style*/ 
popupTitleCondense = 1 << 13, /*condensed text*/ 
popupTitleExtend = 1 << 14, /*extended text*/ 
popupTitleNoStyle = 1 << 15 /*monostyled text*/ 

}; 

enum { 


/*pop-up title characteristics*/ 

popupTitleLeftJust = 0x00000000, /*place title left of pop-up box*/ 
popupTitleCenterJust = 0x00000001, /*center title over pop-up box*/ 
popupTitleRightJust = OxO00000FF, /*place title right of pop-up box*/ 


/*axis constraints for DragControl procedure*/ 


noConstraint = 0, /*no constraint*/ 
hAxisOnly = 1, /*constrain movement to horizontal axis only*/ 
vAxisOnly = 2, /*constrain movement to vertical axis only*/ 
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/*constants for the message parameter in a control definition function*/ 


/*part identifiers for 


he 


drawCntl 
testCntl 
calcCRgns 


initCntl 
dispCntl 
posCntl 
thumbCntl 
dragCntl 
autoTrack 
calcCntlRgn 
calcThumbRgn 
cFrameColor 
cBodyColor 


cTextColor 
cThumbColor 


Data Types 


= 0, 
= 1, 
= 2, 


ll 
CO 
s 


10, 
11, 


struct ControlRecord { 


hi 


struct ControlRecord **nextControl; 


WindowPtr 
Rect 

unsigned char 
unsigned char 
short 

short 

short 

Handle 

Handle 
ProcPtr 

long 

Str255 
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ColorSpec records ina 


/*draw the control or control part*/ 

/*test where mouse button was pressed*/ 
/*calculate region for control or indicator in */ 
/* 24-bit systems*/ 

/*do any additional control initialization*/ 
/*take any additional disposal actions*/ 

/*move indicator and update its setting*/ 
/*calculate parameters for dragging indicator*/ 
/*peform any custom dragging of control or */ 

/* its indicator*/ 

/*execute action procedure specified by your */ 
/* function*/ 
/*calculate region for control*/ 
/*calculate region for indicator*/ 


control color table resource*/ 





= 0, /*frame color; for scroll bars, also foreground */ 
/* color for scroll arrows and gray area*/ 
= 1, /*for scroll bars, background color for scroll */ 
/* arrows and gray area; for other controls, */ 
/* the fill color for body of control*/ 
= 2, /*text color; for scroll bars, unused*/ 
= 3 /*Reserved*/ 
/*next control*/ 
contrlOwner; /*control's window*/ 
contrlRect; /*rectangle*/ 
contrlVis; /*255 if visible*/ 
contrlHilite; /*highlight state*/ 
contrlValue; /*control's current setting*/ 
contrlMin; /*control's minimum setting*/ 
contr1lMax; /*control's maximum setting*/ 
contrlDefProc; /*control definition function*/ 
contrlData; /*data used by contrlDefProc*/ 
contrlAction; /*action procedure*/ 
contr1ilRfCon; /*control's reference value*/ 
contrilTitle; /*control's title*/ 
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typedef struct ControlRecord ControlRecord; 
typedef ControlRecord *ControlPtr, **ControlHandle; 


struct 


}; 


AuxCtlRec { 
Handle acNext; 
ControlHandle acOwner; 


/*handle to next AuxCtlRec*/ 
/*handle to this record's control*/ 


CCTabHandle acCTable; /*handle to color table record*/ 
short acFlags; /*reserved*/ 

long acReserved; /*reserved for future use*/ 

long acRefCon; /*for use by application*/ 


typedef struct AuxCtlRec AuxCtlRec; 


typede 


struct 


he 


f AuxCtlRec *AuxCtlPtr, **AuxCtlHandle; 

CtlcTab { 

long ccSeed; /*reserved; set to 0*/ 

short ccRider; /*reserved; set to 0*/ 

short ctSize; /*number of ColorSpec records in next 
/* field; 3 for standard controls*/ 

ColorSpec ctTable[4]; 


typedef struct CtlCTab CtlCTab; 
£ CtlCTab *CCTabPtr, **CCTabHandle; 


typede 


Control 


Manager Routines 


Creating Controls 


pascal ControlHandle GetNewControl 


(short controlID, WindowPtr owner); 


pascal ControlHandle NewControl 


Drawing Controls 


(WindowPtr theWindow, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible, 
short value, short min, short max, 

short procID, long refCon); 


/*UpdateControls is also spelled as UpdtControl*/ 


pascal 
pascal 
pascal 


pascal 
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void ShowControl 
void UpdateControls 
void DrawControls 


void DrawlControl 


(ControlHandle theControl); 

(WindowPtr theWindow, RgnHandle updateRgn) ; 
(WindowPtr theWindow) ; 

(ControlHandle theControl); 
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Handling Mouse Events in Controls 


pascal short FindControl (Point thePoint, WindowPtr theWindow, 
ControlHandle *theControl); 

pascal short TrackControl (ControlHandle theControl, Point thePoint, 
ProcPtr actionProc); 

pascal short TestControl (ControlHandle theControl, Point thePt); 


Changing Control Settings and Display 

/*some routines have 2 spellings—see Table 5-1 for the alternate spellings*/ 

pascal void SetControlValue (ControlHandle theControl, short theValue) ; 

pascal void SetControlMinimum 
(ControlHandle theControl, short minValue); 


pascal void SetControlMaximum 
(ControlHandle theControl, short maxValue); 


pascal void SetControlTitle (ControlHandle theControl, 


ConstStr255Param title); 
pascal void HideControl (ControlHandle theControl) 
pascal void MoveControl (ControlHandle theControl, short h, short v); 
pascal void SizeControl (ControlHandle theControl, short w, short h); 
( 


pascal void HiliteControl ControlHandle theControl, short hiliteState); 








pascal void DragControl (ControlHandle theControl, Point startPt, 
const Rect *limitRect, 
const Rect *slopRect, short axis); 


pascal void SetControlAction(ControlHandle theControl, ProcPtr actionProc) 


pascal void SetControlColor (ControlHandle theControl, 
CCTabHandle newColorTable); 


Determining Control Values 


/*some routines have 2 spellings—-see Table 5-1 for the alternate spellings*/ 





pascal short GetControlValue 
(ControlHandle theControl); 


pascal short GetControlMinimum 
(ControlHandle theControl); 


pascal short GetControlMaximum 
(ControlHandle theControl); 


pascal void GetControlTitle (ControlHandle theControl, Str255 title); 


pascal long GetControlReference 
(ControlHandle theControl); 


pascal void SetControlReference 








(ControlHandle theControl, long data); 


pascal ProcPtr GetControlAction 
(ControlHandle theControl); 
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pascal short GetControlVariant 
(ControlHandle theControl); 





pascal Boolean GetAuxiliaryControlRecord 
(ControlHandle theControl, 
AuxCtlHandle *acHndl); 


Removing Controls 


pascal void DisposeControl (ControlHandle theControl); 


pascal void KillControls (WindowPtr theWindow) ; 
Application-Defined Routines 


Defining Your Own Control Definition Function 


pascal long MyControl (short varCode, ControlHandle theControl, 
short message, long param) ; 


Defining Your Own Action Procedures 


pascal void MyAction (ControlHandle theControl, short partCode) ; 


pascal void MyIndicatorAction; 


Assembly-Language Summary 


Data Structures 


ControlRecord Data Structure 





0 nextControl long handle to next control in control list 

4 contrlOwner long pointer to this control’s window 

8 contrlRect 8 bytes control’s rectangle 

16 contrlVis 1 byte value of 255 if control is visible 

17 contrlHilite 1 byte highlight state 

18 contrlValue word control’s current setting 

20 contr1lMin word control’s minimum setting 

22 contr1lMax word control’s maximum setting 

24 contrlDefProc long handle to control definition function 
28 contrlData long data used by control definition function 
32 contrlAction long address of action procedure 

36 contr1RfCon long control’s reference value 
40 contrlTitle 256 bytes control title (preceded by length byte) 
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AuxCtlRec Data Structure 


0 acNext long handle to next AuxCt1Rec record in control list 
4 acOwner long handle to this record’s control 
8 acCTable long handle to color table for this control 

12 acFlags word miscellaneous flags 

14 acReserved long reserved for use by Apple Computer, Inc. 

18 acRefCon long for use by application 


Global Variables 


AuxCtlHead First in a linked list of auxiliary control records 

AuxWinHead Contains a pointer to the linked list of auxiliary control records 

DragHook Address of procedure to execute during TrackCont rol and DragControl 
DragPattern Pattern of dragged region’s outline (8 bytes) 
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This chapter describes how your application can use the Dialog Manager to alert users to 
unusual situations and to solicit information from users. For example, in some situations 
your application might not be able to carry out a command normally, and in other 
situations the user must specify multiple parameters before your application can execute 
a command. For circumstances like these, the Macintosh user interface includes these 
two features: 


m alerts—including alert sounds and alert boxes—which warn the user whenever an 
unusual or potentially undesirable situation occurs within your application 


m dialog boxes, which allow the user to provide additional information or to modify 
settings before your application carries out a command 


Read this chapter to learn how and when to implement alerts and dialog boxes. For 
example, your application can use the Dialog Manager to ask the user whether to save 
new or altered documents before quitting and, if the situation arises, to inform the user 
that there is insufficient disk space to save the file. 


Virtually all applications need to implement alerts and dialog boxes. To avoid needless 
development effort, use the Dialog Manager to implement alerts and to create most 
dialog boxes. It is possible, however—and sometimes desirable—to bypass the Dialog 
Manager and instead use Window Manager, Control Manager, QuickDraw, and Event 
Manager routines to create or respond to events in complex dialog boxes. Even if you 
decide not to use the Dialog Manager, read this chapter for information about effective 
human interface design and localization issues regarding dialog boxes. 


To use this chapter, you should be familiar with resources, the Event Manager, the 
Window Manager, and the Control Manager. 


You typically use resources to specify the items you wish to display in alert boxes and 
dialog boxes; for example, you specify the size, location, and appearance of a dialog 
box in a dialog resource—a resource of type 'DLOG'. See the chapter “Introduction to 
the Macintosh Toolbox” in this book for general information about resources; detailed 
information about the Resource Manager and its routines is provided in the chapter 
“Resource Manager” of Inside Macintosh: More Macintosh Toolbox. 


The Dialog Manager offers routines that handle most of the events relating to alerts 
and dialog boxes, but your application still needs to handle a few additional events 
as described in “Writing an Event Filter Function for Alert and Modal Dialog Boxes” 
beginning on page 6-86. See the chapter “Event Manager” in this book for general 
information about events and event handling. 


The Dialog Manager uses the Window Manager to display your alert boxes and dialog 
boxes. Although the Dialog Manager uses most of the Window Manager routines 
necessary to activate and update your alert and dialog boxes, your application needs 
to use Window Manager routines if it creates certain types of dialog boxes—such as 
modeless dialog boxes—as explained in this chapter. See the chapter “Window 
Manager” in this book for general information about windows. 


The Dialog Manager uses the Control Manager to create and display buttons, radio 
buttons, checkboxes, and pop-up menus and to handle events in them. Generally, you 
shouldn’t use any other controls—such as scroll bars—in your dialog boxes. If you need 
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to implement a more complex control, see the chapter “Control Manager” in this book. 
Buttons are the only controls you should use in alert boxes. 


If you include editable text items in your dialog boxes, the Dialog Manager uses TextEdit 
to handle associated editing tasks. For general information on TextEdit, see the chapter 
“TextEdit” in Inside Macintosh: Text. 


This chapter provides a brief introduction to the concepts and functions of alerts and 
dialog boxes, and then it discusses how you can 


m create and display alerts and dialog boxes 


m include controls, informative text, editable text fields, and similar items in your alert 
boxes and dialog boxes 


m respond to events in your alert boxes and dialog boxes 


Introduction to Alerts and Dialog Boxes 


The behaviors and uses of alerts differ from those of dialog boxes. Important distinctions 
also exist between different types of alerts and between different types of dialog boxes. 
You choose among these according to the user’s current situation. 


Your application should give an alert to report an error or to issue a warning to the 

user. An alert can simply play a sound (called an alert sound) for the user, it can display 
an alert box that contains a message and requires an acknowledgment from the user, 

or it can play an alert sound and simultaneously display an alert box. Alert boxes are 
special windows that contain informative text, buttons, and, generally, icons. They 

may also contain pictures. As shown in Figure 6-1, an alert box typically consists of 

text describing why the alert appears and buttons requiring the user to acknowledge 

or rectify the problem. 


Figure 6-1 An alert box used by the Finder 





The Trash contains 1 item. It uses ?5K of 
disk space. Are you sure you want to 
permanently remove it? 





By requiring the user to click a button, an alert box obliges the user to acknowledge the 
alert box before proceeding. To assist the user who isn’t sure how to respond when an 
alert box appears, your application specifies a preferred button—which invokes a 
preferred action—for every alert box. The Dialog Manager draws a bold outline around 
the preferred button so that it stands out from the other buttons in the alert box. The 
outlined button is also the alert box’s default button; if the user presses the Return key 
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or the Enter key, the Dialog Manager acts as if the user had clicked this preferred button. 
For example, if the user presses the Return or Enter key in response to the alert box 
shown in Figure 6-1, the Dialog Manager inverts the OK button for 8 ticks and informs 
the Finder that the OK button has been selected; then the Finder responds by deleting 
the item contained in the Trash. 


Use a dialog box when your application needs more information to carry out a com- 
mand. Commands in menus normally act on only one object. If the user chooses a 
command that your application cannot perform until the user supplies more informa- 
tion, use a dialog box to elicit the information from the user. If a command brings up 
a dialog box, indicate this to your user by placing three ellipsis points (...) after the 
command’s name in the menu. 


A dialog box is a special window that typically resembles a form on which the user 
checks boxes and fills in blanks. Figure 6-2 shows a typical dialog box. 


Figure 6-2 A typical dialog box 

















— SSS Search 


(] Search Backward (Consider Case 














Although an alert typically requires only an acknowledgment to proceed from the user, a 
dialog box ordinarily requires the user to supply information—for instance, by entering 
text or by clicking a checkbox—necessary for completing the command. When you 
create a dialog box that carries out a command, you normally provide OK and Cancel 
buttons. When the user clicks the OK button, your application should perform the 
command according to the information that the user supplied in the dialog box. When 
the user clicks the Cancel button, your application should revoke the command and 
retract all of its actions as though the user had never given the command. Instead of 
using an OK button, you might use a button that describes the action to be performed; 
for example, you might use a Search button in a Search command’s dialog box or a 
Remove button in a Remove command ’s dialog box. For simplicity, this chapter refers to 
the button that performs the action described in the dialog box as the OK button. You 
may even provide more than one button that performs the command, each in a slightly 
different way. For example, ina Change command’s dialog box, you might include a 
Change Selection button to replace only the current selection and a Change All button to 
replace all occurrences throughout the entire document. 


You can use any or all of the following elements in the dialog boxes you create: 
m informative or instructional text 


m rectangles in which text may be entered (initially blank or containing default text that 
can be edited) 
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= controls 
m graphics (icons or QuickDraw pictures) 


m other items as defined by your application 


Types of Alerts 


Every user of every application is liable to do something that the application won’t 
understand or can’t cope with in a normal manner. Alerts give your application a way 
to respond to these situations in a consistent manner. There are two major categories 
of alerts: alert sounds and alert boxes. 


The system alert sound is a sound resource stored in the System file. This sound is 
played whenever system software or your application uses the Sound Manager 
procedure SysBeep. The Sound control panel allows the user to select which sound 

is played as the system alert sound. You can also provide your own alert sound to use 
in place of the system alert sound. 


Use an alert sound for errors that are both minor and immediately obvious. For example, 
if the user tries to backspace past the left boundary of a text field, your application might 
play the alert sound instead of displaying an alert box. Your application can base its 
response on the number of consecutive times an alert condition recurs; the first time, 
your application might simply play a sound, and thereafter it might present an alert box. 
Your application can define different responses for each one of four alert stages. 


An alert box is primarily a one-way communication from your application to the user; 
the only way the user can respond is by clicking buttons. Therefore, your alert boxes 
should contain buttons, but usually they should not contain editable text fields, radio 
buttons, or checkboxes—items that are typically displayed in dialog boxes. 


There are three standard kinds of alert boxes: note alerts, caution alerts, and stop alerts. 
They are distinguished by the icons displayed in their upper-left corners. 


Use a note alert to inform users of a situation that won’t have any disastrous 
consequences if left as is. Usually this type of alert simply offers information, and the 
user responds by clicking the OK button. Occasionally, as shown in Figure 6-3, a note 
alert may ask a simple question and provide a choice of responses. 


Figure 6-3 A note alert 








The color “Mauve” is not very attractive 
= in this context. People with taste may 
complain. Use “Teal” instead? 
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Use a caution alert to alert the user to an operation that may have undesirable results if 
it’s allowed to continue. As shown in Figure 6-4, you should give the user the choice of 
whether to continue the action (by clicking the OK button) or to stop the action (by 
clicking the Cancel button). 


Figure 6-4 A caution alert 





The color “Mauve” shows very poor taste, 
and your career may suffer irreparable 
damage because of it. Use “Teal” instead? 





Use a stop alert to inform the user that a problem or situation is so serious that the 
action cannot be completed. Stop alerts, as illustrated in Figure 6-5, typically have only 
a single button (OK), because all the user can do is acknowledge that the action cannot 
be completed. 


Figure 6-5 A stop alert 





context, because it is too ugly. Try using 


i) You cannot use the color “Mauve” in this 
a more attractive color such as “Teal.” 





You can also create custom alert boxes containing in the upper-left corners either your 
own icons or blank spaces. Plate 2 at the front of this book illustrates an alert box that 
the SurfWriter application displays when the user chooses the About command from the 
Apple menu. After reading the information in this alert box, the user clicks the OK 
button to dismiss it. 


Types of Dialog Boxes 


Dialog boxes should always require information from the user as well as communicate 
information to the user. That is, the purpose of a dialog box is to carry on a dialog 
between the user and your application—typically, in preparation for the execution of 

a command. Your dialog boxes can include editable text fields and controls such as 
checkboxes and radio buttons. With these, the user supplies the information your 
application needs to carry out the command. There are three types of dialog boxes: 
modal dialog boxes, movable modal dialog boxes, and modeless dialog boxes. These 
are described in the next three sections. 
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Modal Dialog Boxes 


Before allowing the user to proceed with any other work, many dialog boxes require the 
user to click a button. The only response a user receives when clicking outside the dialog 
box is an alert sound. This type is called a modal dialog box because it puts the user in 
the state or “mode” of being able to work only inside the dialog box. Also called a 
fixed-position modal dialog box (to differentiate it from a movable modal dialog box), 
this type of dialog box looks like an alert box that includes other types of controls in 
addition to buttons. Figure 6-6 shows the modal dialog box that SurfWriter displays after 
the user chooses the Spell Check command. 


Figure 6-6 A modal dialog box 








WipeOut typing correction options: 


CJ] Ignore Words in All Caps 


C] Ignore Slang Terms 





IMPORTANT 

Because the user must explicitly dismiss a modal dialog box before 
doing anything else, you should use a modal dialog box only when it’s 
essential for the user to complete an operation before performing any 
other work. Fixed-position modal dialog boxes restrict the user’s 
freedom of action; therefore, use them sparingly. As a rule of thumb, 
use a modeless dialog box whenever possible, use a movable modal 
dialog box whenever you can’t use a modeless dialog box, and use a 
fixed-position modal dialog box only when you can’t implement the 
dialog box as modeless or movable. « 


A modal dialog box usually has at least two buttons: OK and Cancel. When the user 
clicks the OK button, your application should perform the command according to the 
information provided by the user and then remove the modal dialog box. You can give 
the OK button a more descriptive title if you wish. When the user clicks the Cancel 
button, your application should revoke any actions it took since displaying the modal 
dialog box, and then it should remove the modal dialog box. Always label this button 
“Cancel.” Your dialog boxes can have additional buttons as well; these may or may not 
dismiss the dialog box. 


Every dialog box you create should have a default button—that is, one whose action is 
invoked when the user presses the Return or Enter key. Unless you provide your own 
event filter function, the Dialog Manager treats the first item you specify in a description 
of a dialog box as the default button (that is, so long as the first item is a button). You use 
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an event filter function, described in “Writing an Event Filter Function for Alert and 
Modal Dialog Boxes” beginning on page 6-86, to supplement the Dialog Manager’s 
ability to handle events; for example, an event filter function can also test for disk- 
inserted events and can allow background applications to receive update events. If you 
provide your own event filter function, it should test for key-down events involving the 
Return and Enter keys and respond as if the default button were clicked. The default 
button should invoke the preferred action, and you should try to design the preferred 
action to be safe—that is, so that it doesn’t cause loss of data. 


Although the Dialog Manager draws bold outlines around default buttons in alert 
boxes, it does not draw bold outlines around those in dialog boxes. To indicate the 
preferred action, your application should outline the default button. “Using an 
Application-Defined Item to Draw the Bold Outline for a Default Button” beginning on 
page 6-56 shows a method you can use to outline a button. If you don’t outline a 
button in a dialog box, none should be the default button, and you must ensure in your 
event filter function that pressing the Return or Enter key has no effect. 


Movable Modal Dialog Boxes 


The user sometimes needs to see windows obscured by an overlying modal dialog box. 
In this case, you should use a movable modal dialog box instead of a fixed-position 
modal dialog box. The movable modal dialog box is a modal dialog box that has a title 
bar so that the user can move the box by dragging its title bar. 


The movable modal dialog box contains no close box and should contain no zoom box. 
These visual clues indicate that the user can move the dialog box, but that the dialog 
box is modal—that is, the user must respond to the dialog box before performing any 
other work in your application. If the user clicks another window belonging to your 
application, it should play the system alert sound. Your application removes a movable 
modal dialog box only after the user clicks one of its buttons. Unlike regular modal 
dialog boxes, however, this type of dialog box allows the user to bring another 
application to the front by clicking one of its windows or by choosing the application 
name from the Application or Apple menu. 


Figure 6-7 shows the movable modal dialog box that the Finder displays after the user 
chooses the Find command from the File menu. 


Figure 6-7 A movable modal dialog box 
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It’s important to consider whether you can use a modeless dialog box instead of a modal 
or a movable modal dialog box—especially to preserve the user’s ability to perform any 
task in any order. 


Movable modal dialog boxes should generally respond like modal dialog boxes. Note, 
however, that users should be able to switch between your application and another 
application (thereby sending your application to the background) when you display a 
movable modal dialog box—an action users cannot perform with modal dialog boxes. 
For example, Macintosh system software uses several movable modal dialog boxes to 
show that the Finder is busy with a time-consuming operation (such as file copying), yet 
a user can still switch the Finder to the background. 


Modeless Dialog Boxes 


Other dialog boxes do not require the user to respond before doing anything else; these 
are called modeless dialog boxes. Whenever possible, you should try to implement your 
dialog boxes as modeless. As shown in Figure 6-8, a modeless dialog box looks like a 
document window. The user should be able to move it, make it inactive and active again, 
and close it like any document window. Unlike a document window, it consists mostly 
of buttons and other controls instead of text, and it contains no scroll bars and no size 
box. (A modeless dialog box should not have a size box or scroll bars; if you need these 
features, use the Window Manager to create a window.) 


Figure 6-8 A modeless dialog box 
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When you display a modeless dialog box, you must allow the user to perform other 
operations—such as working in document windows—without dismissing the dialog 
box. When a user clicks a button in a modeless dialog box, your application should not 
remove it; instead, the dialog box should remain on the desktop so that the user can 
perform the command again. Because of the difficulty in revoking the last action invoked 
from a modeless dialog box, it typically does not have a Cancel button, although it may 
have a Stop button. A Stop button in a modeless dialog box is useful for halting long 
printing or searching operations, for example. 


When finished with a modeless dialog box, the user can click its close box or choose 
Close from the File menu (when the dialog box is the active window). Your application 
should then remove the modeless dialog box. A modeless dialog box is also dismissed 
implicitly when the user chooses Quit. It’s usually helpful to the user for your 
application to remember the contents of the dialog box after it’s dismissed. This way, 
when the user invokes the dialog box again, even after the user closes and reopens your 
application, you can restore the dialog box exactly as it was. 
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Items in Alert and Dialog Boxes 


All dialog boxes and alert boxes contain items—such as icons, text, controls, and 
QuickDraw pictures. You use resources called item lists to specify which items you want 
to appear in your alert boxes and dialog boxes. You can even define your own items— 
for example, a picture whose appearance changes. Figure 6-9 illustrates most of these 
item types. 


Figure 6-9 Typical items in a dialog box 
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Your application enables or disables the items it includes in its dialog and alert boxes. An 
enabled item is one for which the Dialog Manager reports user events involving that 
item; for example, the Dialog Manager reports to the application when a user clicks the 
enabled Cancel button shown in Figure 6-9. A disabled item is one for which the Dialog 
Manager does not report events. For example, the Dialog Manager does not report to the 
application when the user clicks or drags the static text item “Save this document as” in 
Figure 6-9 because that item is disabled. 


Don’t confuse a disabled item with an inactive control. When you don’t want the 

Control Manager to display visual responses to mouse events in a control, you make 

it inactive by using the Control Manager procedure HiliteControl. For example, 
until the user types a filename, the Save button in Figure 6-9 is inactive. The Control 
Manager displays an inactive control in a way (such as by dimming it) that shows it’s 
inactive. The Dialog Manager makes no visual distinction between a disabled item and 
an enabled item; the Dialog Manager simply doesn’t inform your application when the 
user clicks a disabled item. 


You should use HiliteControl to dima control in dialog box whenever the user can’t 
use that control. For example, Figure 6-8 shows a modeless dialog box with a dimmed 
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Stop button. The Stop button is dimmed because it has no effect until the user clicks the 
Search button. When the user initiates the search operation by clicking the Search button, 
the Stop button becomes active, and the Search button is dimmed. 


You should use the Control Manager procedure HiliteControl to make the buttons 
and other controls inactive in a modeless or movable modal dialog box when you 
deactivate it. The HiliteControl procedure dims inactive buttons, radio buttons, 
checkboxes, and pop-up menus to indicate to the user that clicking these items has no 
effect while the dialog box is in the background. When you activate the dialog box again, 
use Hil iteControl to make the controls active again. 


You store information about all dialog or alert box items in an item list resource. When 
you use Dialog Manager routines to invoke alert boxes or create dialog boxes, the 
Dialog Manager gets most of the descriptive information about them from resources. 
The Dialog Manager calls the Resource Manager to read into memory what it needs 
from the resource file. 


Events in Alert and Dialog Boxes 


Handling events in an alert box is very simple: after you invoke an alert box, the Dialog 
Manager handles most events for you by automatically calling the ModalDialog 
procedure. 


To handle events in a modal dialog box, your application must explicitly call the 
ModalDialog procedure after displaying the dialog box. 


In either case, when an enabled item is clicked, the Dialog Manager returns the 
item number. You'll then do whatever is appropriate in response to that click. For 
mouse-down events outside the alert box or modal dialog box, the ModalDialog 
procedure plays the system alert sound and gets the next event. 


The Dialog Manager automatically removes an alert box when the user clicks any 
enabled item. For a modal dialog box, your application should continue calling 
ModalDialog until the user selects the OK or Cancel button, and then—after 
responding appropriately to the user’s selection—your application should remove 
the dialog box. 


When it receives an event, ModalDialog passes the event to an event filter function 
before handling the event itself. You should provide an event filter function as a 
secondary event-handling loop for events that ModalDialog doesn’t handle. For both 
alert and modal dialog boxes, you should provide a simple event filter function that 
performs the following tasks: 


m return TRUE and the item number for the default button if the user presses the Return 
or Enter key 





m retum TRUE and the item number for the Cancel button if the user presses the Esc 
key or the Command-period key combination 


m update your windows in response to update events (this also allows background 
applications to receive update events) and return FALSE 








m return FALSE for all events that your event filter function doesn’t handle 
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You can also use the event filter function to test for and respond to keyboard equivalents 
and more complex events—for instance, the user dragging the cursor within an 
application-defined item. 


For your application’s modeless and movable modal dialog boxes, you can pass events 
to the IsDialogEvent function, or you can use your own event-handling code to 

learn whether the events need to be handled as part of a dialog box. If they do, call 

the DialogSelect function to assist you in handling them instead of calling the 
ModalDialog procedure. Your application should not remove a modeless dialog box 
unless the user clicks its close box or chooses Close from the File menu when the 
modeless dialog box is the active window. Your application should remove a movable 
modal dialog box only after the user clicks one of its enabled buttons. 


Instead of using the IsDialogEvent or DialogSelect function to handle events 
within modeless and movable modal dialog boxes, you can use Control Manager, 
Window Manager, and TextEdit routines (such as FindWindow, BeginUpdate, 
EndUpdate, FindControl, TrackControl, and TEClick) to handle these events 
without the aid of the Dialog Manager. 





Alert Boxes, Dialog Boxes, and the Window Manager 


The Dialog Manager uses the Window Manager to draw your alert boxes and dialog 
boxes. You can use Window Manager or QuickDraw routines to manipulate an alert 
box or a dialog box just like any other window—showing it, hiding it, moving it, and 
resizing it. 


The Dialog Manager gets most of the descriptive information about alerts and dialog 
boxes from resources in a resource file. An alert resource is a resource that describes an 
alert, and a dialog resource is a resource that describes a dialog box. Both are analogous 
to a window resource. (In addition to providing information that the Dialog Manager 
passes to the Window Manager, you also include in your alert resources and dialog 
resources additional information that the Dialog Manager alone uses. These resources 
are described more fully in “Creating Alert Sounds and Alert Boxes” beginning on 

page 6-18 and “Creating Dialog Boxes” beginning on page 6-23.) 


When you create an alert box, the Dialog Manager always passes to the Window 
Manager the dBoxProc window definition ID for the alert box; this is so that all alert 
boxes have the same standard appearance and behavior. The Window Manager always 
displays an alert box in front of all other windows. Because an alert box requires the user 
to respond before doing anything else, and the response dismisses the alert box, your 
application typically won’t need to use any Window Manager or QuickDraw routines to 
manipulate an alert box. 





The GetNewDialog function for creating dialog boxes is similar to the Window 
Manager function Get NewWindow. When you call GetNewDialog to create a 

dialog box, you supply the same information as when you create a window with 
GetNewWindow. For example, you use a resource to specify the window definition ID, 
which determines how the dialog box looks and behaves, and a rectangle that defines 
the dimensions of the dialog box’s graphics port. As for any window, you specify the 
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plane of the dialog box (which, by convention, should initially be frontmost), and you 
specify whether it is initially visible or invisible. If you create a dialog box that is initially 
invisible—for example, if you need to set a control’s value before displaying it—you use 
the Window Manager procedure ShowWindow to display the dialog box. 


The Dialog Manager creates the dialog window by calling the Window Manager 
function NewCWindow and then setting the window class in the window record to 
indicate that it’s a dialog box. The Dialog Manager procedures for disposing of a dialog 
box, CloseDialog and DisposeDialog, are analogous to the Window Manager 
procedures CloseWindow and DisposeWindow. 


When you create a dialog box (as described in “Creating Dialog Boxes” beginning on 
page 6-23), use the window definition ID of dBoxProc for modal dialog boxes. Use 
the noGrowDocProc window definition ID for modeless dialog boxes. (If your dialog 
box absolutely needs a size box or scroll bars, you should use the Window Manager 
to create the window instead of using the Dialog Manager.) And finally, use the 
movableDBoxProc window definition ID to create movable modal dialog boxes. 





The Dialog Manager provides routines for handling most events in alert boxes and 
dialog boxes. For example, your application does not need to use such routines as the 
Window Manager function F indWindow and the Control Manager function 
TrackControl to determine when and where a mouse-down event occurs within an 
alert box’s buttons. The Dialog Manager tells you which button the user clicks, and your 
application needs only to respond appropriately to the click. The Dialog Manager also 
automatically handles update and activate events for your alert boxes and dialog boxes. 
“Handling Events in Alert and Dialog Boxes” beginning on page 6-77 describes in detail 
how to use the Dialog Manager to help your application handle events. 


About the Dialog Manager 


The Dialog Manager greatly simplifies the task of creating alert boxes and simple modal 
dialog boxes. Whenever you need to create an alert box, you'll save yourself much effort 
by relying on the Dialog Manager. (If you need only to play the system alert sound 
without ever displaying an alert box for an error condition, you can use the Sound 
Manager procedure SysBeep instead of using the Dialog Manager. See Inside Macintosh: 
Sound for more information about the SysBeep procedure.) 


You may find, however, that the advantages of using the Dialog Manager begin to 
diminish for dialog boxes if you make them very complex. For complex modal dialog 
boxes (particularly those containing multipart controls or multiple application-defined 
items) and for many movable modal and modeless dialog boxes, you may find it more 
convenient to implement your own dialog boxes using the Window Manager to create 
standard windows and using the Control Manager, QuickDraw, and the Event Manager 
to handle the tasks assumed by the Dialog Manager. 


There are two main issues to consider when deciding whether to use the Dialog Manager: 


m whether to use the Window Manager and the Control Manager instead of the Dialog 
Manager to create a dialog box 
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m whether to use the Event Manager, Window Manager, Control Manager, and TextEdit 
instead of the Dialog Manager to handle events 


You may, for example, want to create complex dialog boxes by using the Dialog 
Manager, but then use the Event Manager, Window Manager, Control Manager, and 
TextEdit to handle events inside your normal event loop. With regard to movable modal 
and modeless dialog boxes, the sample code in this chapter illustrates such a hybrid 
approach: it uses the Dialog Manager to create the dialog boxes, but it uses normal 
event-handling code to determine an appropriate action according to which type of 
window is frontmost. When a modeless or movable modal dialog box is in front, this 
chapter illustrates how to take actions specific to that dialog box. 


If you draw your own dialog box in a standard window without using the Dialog 
Manager, you won't be able to use Dialog Manager routines to help handle events, 
but in return you'll be able to update the window more quickly and extend its event 
handling more easily. Here are some situations that tend to diminish the advantages 
of using the Dialog Manager to create dialog boxes or handle events involving them: 


m The dialog box contains more than 20 items. 

m Youneed a multipart control, such as a scroll bar. 

m You need to move items offscreen and onscreen. 

m Youneed to display a moving indicator, such as a progress indicator. 


m You need to display a list in the dialog box. (For more information on lists, see the 
chapter “List Manager” in Inside Macintosh: More Macintosh Toolbox.) 


m You need to display text in a font other than the system font. 


m Your application must respond to events other than mouse-down events, key-down 
events inside editable text items, and a few key-down events for keyboard equivalents 
when your application displays the dialog box. 


If none of these situations applies to the dialog box you want to create, then you should 
definitely use the Dialog Manager. If only one situation applies, you should probably use 
the Dialog Manager. If two or more of these situations apply, you may find that it is 
better to create and manage a standard window that operates like a dialog box instead of 
using the Dialog Manager to create or manage it. 


Using the Dialog Manager 


You can use the Dialog Manager to 
m alert users to critical situations 
m carry ona dialog with users when your application needs their input 


With Dialog Manager routines, you invoke alert boxes or create dialog boxes in windows 
whose contents are, in turn, managed by the Dialog Manager. The Dialog Manager 
automatically handles update events, activate events, cursor tracking, and most 
text-editing tasks for your alert and dialog boxes. 
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To implement alerts and dialog boxes, you generally 
m create an alert resource or a dialog resource in a resource file 


m create another resource to specify a list of items—such as controls, informative text, 
and pictures—to be displayed in the alert box or dialog box 


m create and display the alert box or dialog box 
m respond as appropriate to events relating to your alert or dialog box 


m close the dialog box when you are finished with it (for alert boxes, the Dialog 
Manager automatically performs this for you) 


These tasks are explained in greater detail in the rest of this chapter. 


Before using the Dialog Manager, you must initialize QuickDraw, the Font Manager, the 
Window Manager, the Menu Manager, and TextEdit, in that order. Then initialize the 
Dialog Manager by using the InitDialogs procedure. 


The Dialog Manager uses the system alert sound for signaling the user during various 
alert stages. If you want to use alert sounds other than the system alert sound, write 
your own sound procedure (as illustrated in Listing 6-3 on page 6-22) and call the 
ErrorSound procedure to make it the current sound procedure. 





If you want to display static text or editable text in a font other than the system font, you 
can use the SetDialogFont procedure. However, there are a number of caveats 
regarding this procedure. For descriptions of these caveats, see “Special Considerations” 
in the description of SetDialogFont on page 6-105. 


System 7 and earlier versions of the Communications Toolbox add several new routines 
(namely, AppendDITL, ShortenDITL, and CountDITL) that make it easier for you 

to add items to, remove items from, and count the number of items in a dialog box. 
Before calling these routines, you should make sure that they are available by using the 
Gestalt function with the gestaltDITLExtAttr selector. Test the bit field indicated 
by the gestaltDITLExtPresent constant in the response parameter. If the bit is set, 
then AppendDITL, ShortenDITL, and CountDITL are available. 








CONST gestaltDITLExtPresent= 0; {if this bit is set, then } 
{ AppendDITL, ShortenDITL, } 
{ & CountDITL are available} 





The Gestalt function is described in the chapter “Gestalt Manager” of Inside Macintosh: 
Operating System Utilities. 


Creating Alert Sounds and Alert Boxes 


To create an alert, use one of these functions: NoteAlert, CautionAlert, StopAlert, 
and Alert. Icons associated with the first three functions appear in the upper-left corner 
of the alert boxes, as previously shown in Figure 6-3, Figure 6-4, and Figure 6-5. The 
Alert function allows you to display your own icon or to have no icon at all in the 
upper-left corner of the alert box. 


Using the Dialog Manager 


CHAPTER 6 


Dialog Manager 


These functions take descriptive information about the alert from an alert resource that 
you provide. An alert resource has the resource type 'ALRT'. When you call one of these 
functions, you pass it the resource ID of the alert resource and a pointer to an event filter 
function. These functions create and display an alert box. When the user clicks a button 
in an alert box, these functions return the button’s item number and close the alert box, 
at which time you respond appropriately to the user’s click, as described in “Responding 
to Events in Alert Boxes” beginning on page 6-81. 


Here’s an example of how to create the caution alert shown in Figure 6-10. 


VAR 
myAlertiItem: Integer; 
myAlertItem := CautionAlert (kSaveAlertID, @MyEventFilter) ; 


Figure 6-10 An alert box to save changes to a document 
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You should specify a pointer to an event filter function when you call the Alert, 
StopAlert, CautionAlert, and NoteAlert functions. You should provide an event 
filter function as a secondary event-handling loop for events that ModalDialog doesn’t 
handle. In this example, a pointer to MyEventFilter is specified for the event filter 
function. You can use the standard event filter function by passing NIL in this parameter. 
The standard event filter function allows users to press the Return or Enter key in lieu of 
clicking the default button. As described in “Writing an Event Filter Function for Alert 
and Modal Dialog Boxes” beginning on page 6-86, your application should provide a 
simple event filter function that also allows background applications to receive update 
events. You can use the same event filter function in most or all of your alert boxes and 
modal dialog boxes. 


Continuing with the previous example, an application-defined constant 
(kSaveAlertID) specifies the resource ID of an alert resource in a parameter to 
the CautionAlert function. Listing 6-1 shows how this alert resource appears 

in Rez input format. (Rez is the resource compiler provided with Apple’s Macintosh 
Programmer’s Workshop [MPW], available from APDA.) 


Listing 6-1 Rez input for an alert resource 
resource 'ALRT' (kSaveAlertID, purgeable) { /*alert resource*/ 


{94, 80, 183, 438}, /*rectangle for alert box*/ 
kSaveAlertDITL, /*use the 'DITL' with res ID 200*/ 
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/*alert stages, starting with #4; at each */ 
/* stage, make OK the default, display the */ 
/* alert box, & play the system alert sound*/ 


visible, soundl, /*4th consecutive error*/ 
visible, soundl, /*3rd consecutive error*/ 
visible, soundl, /*2nd consecutive error*/ 
visible, soundl, /*1lst error*/ 


alertPositionParentWindow /*place over document window*/ 


i 
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An alert resource contains the following information: 


m arectangle, given in global coordinates, that determines the alert box’s dimensions 
and, optionally, its position; these coordinates specify the upper-left and lower-right 
corners of the alert box 


m the resource ID of the item list for the alert box 
m the actions to be taken at each of four alert stages 


m as an option, a constant (either alertPositionParentWindow, 
alertPositionMainScreen, oralertPositionParentWindowScreen) 
that tells the Dialog Manager where to position the alert box (available only to 
applications running in System 7) 


In Listing 6-1, the coordinates (94,80,183,438) specify the dimensions of the alert box, and 
the alertPositionParentWindow constant causes the Dialog Manager to place the 
alert box just below the title bar of the user’s document window. If you don’t supply a 
positioning constant, the Dialog Manager places the alert box at the global coordinates 
you specify for the alert box’s rectangle. The positioning constants for alert boxes are 
explained in “Positioning Alert and Dialog Boxes” beginning on page 6-62. 


In Listing 6-1, the application-defined constant kSaveAlertDITL represents the 
resource ID for the item list resource. “Providing Items for Alert and Dialog Boxes” 
beginning on page 6-26 describes how to create an item list resource. 


Your application can base its response on the number of consecutive times an alert 
condition recurs. In Listing 6-1, the alert resource specifies that each consecutive time 
the user repeats the action that invokes this caution alert, the Dialog Manager should 
perform the following: outline the OK button and treat it as the default button, display 
the alert box (that is, make it “visible”), and play a single system alert sound. 


Your application can define different responses for each of four stages of an alert. This is 
most appropriate for stop alerts—those that signify that an action cannot be completed— 
especially when that action has a high probability of being accidental (for example, when 
the user chooses the Cut command when no text is selected). Under such a circumstance, 
your application might simply play the system alert sound the first two times the user 
makes the mistake, and for subsequent mistakes it might also present an alert box. Every 
consecutive occurrence of the mistake after the fourth alert stage is treated as a 
fourth-stage alert. 
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For example, a user might try to paste a graphic outside the page margins of a simple 
page-layout program; the first time the user tries this, the application—using the Dialog 
Manager—may simply play the system alert sound for the user. If the user repeats the 
mistake, the application may play the system alert sound again. But when the user 
repeats the error for the third consecutive time, the application may display an alert box 
like the one shown in Figure 6-11. If the user makes the same mistake immediately after 
dismissing this alert box, the alert box reappears, and it continues doing so until the user 
corrects or abandons the improper action. 


Figure 6-11 An alert box displayed only during the third and fourth alert stages 
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Listing 6-2 shows the alert resource used to specify the stop alert displayed in 

Figure 6-11. Notice that the fourth alert stage is listed first, and the first alert stage is 
listed last. At the third alert stage, the application displays an alert box but does not 
play the system alert sound. If the user repeats the mistake a fourth consecutive time, 
the application plays the system alert sound and displays the alert box as well. 


Listing 6-2 Specifying different alert responses according to alert stage 


resource 'ALRT' (kStopAlertID, purgeable) { /*alert resource*/ 


{40, 40, 127, 353}, /*rectangle for alert box*/ 

kStopAlertDITL, /*use the 'DITL' with res ID 300*/ 

{ /*alert stages, starting with #4*/ 

OK, visible, soundl, /*4th err: show alert box, play alert sound*/ 
OK, visible, silent, /*3rd err: show alert box, don't play sound*/ 


OK, invisible, soundl, /*2nd err: play sound, don't show alert box*/ 
OK, invisible, soundl, /*1lst err: play sound, don't show alert box*/ 
}, 
alertPositionParentWindow /*place over document window*/ 

}; 


The actions for each alert stage are specified by the following three pieces of information: 


a Which button is the default button—the OK button (that is, the first item in the item 
list resource) or the Cancel button (that is, the second item in the item list resource). 
The Dialog Manager automatically draws a bold outline around the default button, 
and when the user presses the Return or Enter key, the Dialog Manager treats—or 
your event filter function should treat—that keyboard event as a click in the default 
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button. The OK and Cancel buttons are described in detail in “Providing Items for 
Alert and Dialog Boxes” beginning on page 6-26. At each alert stage, you can change 
the default button, although it’s difficult to imagine a scenario where changing the 
default button would be helpful to the user. In the previous example, the OK button is 
the default. 


mu Whether the alert box is to be displayed. If you specify the visible constant for 
an alert stage, the alert box is displayed; if you specify the invisible constant, it is 
not. In Listing 6-2, the alert box is not displayed the first two consecutive times the 
user repeats the mistake, but it is displayed for all subsequent consecutive times. 


a Which of four possible sounds (if any) should be emitted at this stage of the alert. In 
the previous example, the first, second, and fourth alert stages play a single system 
alert sound, but the third stage plays no sound. 


By default, the Dialog Manager uses the system alert sound. The sound1 constant, used 
in Listing 6-2, tells the Dialog Manager to play the system alert sound once; you can also 
specify the sound2 and sound3 constants, which cause the Dialog Manager to play the 
system alert sound two and three times, respectively, each time at the same pitch and 
with the same duration. The volume of the sound depends on the current speaker 
volume setting, which the user can adjust in the Sound control panel. If the user has set 
the speaker volume to 0, the menu bar blinks once in place of each sound that the user 
would otherwise hear. 


If you want the Dialog Manager to play sounds other than the system alert sound, write 
your own sound procedure and then call ErrorSound and pass it a pointer to your 
sound procedure. The ErrorSound procedure (described on page 6-104) makes your 
sound procedure the current sound procedure. For example, you might create a sound 
procedure named MyAlert Sound, as shown in Listing 6-3. 





























Listing 6-3 Creating your own sound procedure for alerts 
PROCEDURE MyAlertSound (soundNo: Integer); 
BEGIN 
CASE soundNo OF 
0: PlayMyWhisperAlert; {sound for silent constant in alert resources} 
1: PlayMyBellAlert; {sound for soundl constant in alert resources} 
2: PlayMyDrumAlert; {sound for sound2 constant in alert resources} 
3: PlayMyTrumpetAlert; {sound for sound3 constant in alert resources} 
OTHERWISE ; 
END; {of CASE} 
END; 
For each of the four alert stages that can be reported in the soundNo parameter, your 
procedure can emit any sound that you define. 
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As previously explained, the dimensions of the rectangle you specify in the alert 
resource determine the dimensions of the alert box. You can also let the rectangle 
coordinates serve as global coordinates that position the alert box, or you can let the 
Dialog Manager automatically locate it for you according to three standard positions. 
Listing 6-2 on page 6-21, for example, uses the alertPositionParentWindow 
constant to position the alert box over the document window where the user is working. 
For details about these standard positions, see “Positioning Alert and Dialog Boxes” 
beginning on page 6-62. 


Creating Dialog Boxes 


To create a dialog box, use the Get NewDialog or NewDialog function. You should 
usually use GetNewDialog, which takes information about the dialog box from a 
dialog ('DLOG') resource in a resource file. Like window resources, dialog resources 
isolate descriptive information from your application code for ease of modification 

or translation to other languages. The rest of this section describes how to use 
GetNewDialog. Although it’s generally not recommended, you can also use the 
NewDialog or NewColorDialog function and pass it the necessary descriptive 
information in individual parameters instead of using a dialog resource. See page 6-118 
for a description of NewDialog and page 6-115 for a description of NewColorDialog. 


The Get NewDialog function creates a data structure (called a dialog record) of type 
DialogRecord from the information in the dialog resource and returns a pointer to it. 
A dialog record includes a window record. When you use GetNewDialog, the Dialog 
Manager sets the windowKind field in the window record to dialogKind. As 
explained in “Displaying Alert and Dialog Boxes” beginning on page 6-61, you can use 
this pointer with Window Manager or QuickDraw routines to display and manipulate 
the dialog box. 


When you use GetNewDialog, you pass it the resource ID of the dialog resource, an 
optional pointer to the memory to use for the dialog record, and the window pointer 
Pointer (-1), which causes the Window Manager to display the dialog box in front of 
all other windows. 


If you pass NIL for the memory pointer, the dialog record is allocated in your 
application’s heap. Passing NIL is appropriate for modal dialog boxes and movable 
modal dialog boxes, but—if you are creating a modeless dialog box—this can cause your 
heap to become fragmented. In the case of modeless dialog boxes, therefore, you should 
allocate your own memory as you would for a window; allocating window memory is 
described in the chapter “Window Manager” in this book. 


Here’s an example of how to create the dialog box shown in Figure 6-12. 


VAR 
theDialog: DialogPtr; 
theDialog := GetNewDialog(kSpellCheckID, NIL, Pointer(-1)); 
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Figure 6-12 A simple modal dialog box 





WipeOut typing correction options: 


CJ Ignore Words in All Caps 


C] Ignore Slang Terms 








This example uses an application-supplied constant (kSpel1CheckID) to specify the 
resource ID number of a dialog resource. Listing 6-4 shows how this dialog resource 
appears in Rez input format. 


Listing 6-4 Rez input for a dialog resource 
ource 'DLOG' (kSpellCheckID, purgeable) { /*dialog resource*/ 
{62, 184, 216, 448}, /*rectangle for dialog box*/ 
dBoxProc, /*window definition ID for modal dialog box*/ 
visible, /*display this dialog box immediately*/ 
noGoAway, /*don't draw a close box*/ 
0x0, /*initial refCon value of 0*/ 
kSpellCheckDITL, /*use item list with res ID 400*/ 
"Spellcheck Options", /*title if this were a modeless dialog box*/ 


alertPositionParentWindow /*place over document window*/ 


The dialog resource contains the following information: 


m arectangle, given in global coordinates, that determines the dialog box’s 
dimensions and, optionally, position; these coordinates specify the upper-left 
and lower-right corners 


m the window definition ID, which specifies the window definition function and 
variation code for the type of dialog box 


m aconstant (either visible or invisible) that specifies whether the dialog box 
should be drawn on the screen immediately 


m™ aconstant (either noGoAway or goAway); use goAway only to specify a close box in 
the title bar of a modeless dialog box 


m areference value of type LongInt, which your application may use for any purpose 


m the resource ID of the item list resource for the dialog box 
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m a text string used for the title of a modeless or movable modal dialog box 


m as an option, a constant (either alertPositionParentWindow, 
alertPositionMainScreen, oralertPositionParentWindowScreen) that 
tells the Dialog Manager how to position the dialog box (available only to applications 
running in System 7) 

In the example, a rectangle with coordinates (62,184,216,448) specifies the dimensions of 

the dialog box, and the alertPositionParentWindow constant causes the Dialog 

Manager to place the dialog box just below the title bar of the user’s document window. 

If you don’t supply a positioning constant, the Dialog Manager places the dialog box at 

the global coordinates you specify for the dialog box’s rectangle. Positioning constants 

for dialog boxes are explained in “Positioning Alert and Dialog Boxes” beginning on 

page 6-62. 


In the example, the dBoxProc window definition ID is used. Use the following window 
definition IDs for specifying dialog box types: 





Window definition ID Dialog box type 

dBoxProc Modal dialog box 
movableDBoxProc Movable modal dialog box 
noGrowDocProc Modeless dialog box 


In each case, the Dialog Manager uses the Window Manager to draw the appropriate 
window frame. Figure 6-6 on page 6-10 shows an example of a modal dialog box drawn 
with the dBoxProc window definition ID, Figure 6-7 on page 6-11 shows an example of 
a movable modal dialog box drawn with the movableDBoxProc window definition ID, 
and Figure 6-8 on page 6-12 illustrates a modeless dialog box drawn with the 
noGrowDocProc window definition ID. 


Listing 6-4 specifies the visible constant so that the dialog box is drawn immediately. 
If you use the invisible constant, the dialog box is not drawn until your application 
uses the Window Manager procedure ShowWindow to display the dialog box. 


Use the goAway constant only with modeless dialog boxes. For modal dialog boxes and 
movable modal dialog boxes, use the noGoAway constant, as shown in the example. 


Notice that because the example does not make use of the reference constant, 0 (0x0) is 
provided as a filler. However, you may wish to make use of this constant. For example, 
your application can store a number that represents a dialog box type, or it can store 

a handle to a record that maintains state information about the dialog box or other 
window types, as explained in the chapter “Window Manager” in this book. You can use 
the Window Manager procedure SetWRefCon at any time to change this value in the 
dialog record for a dialog box, and you can use the Get WRefCon function to determine 
its current value. 


Listing 6-4 uses an application-defined constant that specifies the resource ID for the 
item list. The next section, “Providing Items for Alert and Dialog Boxes,” describes how 
to create an item list. 
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Supply a text string in your dialog resource when you want a modeless dialog box or a 
movable modal dialog box to have a title. You can specify an empty string for a title bar 
that contains no text. The example specifies the string “Spellcheck Options” for code 
readability but, because the example creates a modal dialog box, no title bar is displayed. 


You can let the Dialog Manager automatically locate the dialog box according 

to three standard positions. Listing 6-4 on page 6-24, for example, specifies the 
alertPositionParentWindow constant to position the dialog box over the 
document window where the user is working. For details on these standard positions, 
see “Positioning Alert and Dialog Boxes” beginning on page 6-62. 


Providing Items for Alert and Dialog Boxes 


You use an item list ('DITL') resource to store information about all the items (text, 
controls, icons, or pictures) in an alert or dialog box. As described in “Creating Alert 
Sounds and Alert Boxes” beginning on page 6-18 and “Creating Dialog Boxes” 
beginning on page 6-23, you specify the resource ID of the item list resource in the alert 
('ALRT') resource or dialog ('DLOG ') resource. 


Within an item list resource for an alert box or a dialog box, you specify its static text, 
buttons, and the resource IDs of icons and QuickDraw pictures. In addition, you can 
specify checkboxes, radio buttons, editable text, and the resource IDs of other types of 
controls (such as pop-up menus) in an item list resource for a dialog box. 


Figure 6-13 shows an example of an alert box displayed by the SurfWriter application 
when the user chooses the About command from the Apple menu. To display its own 
icon in the upper-left corner of the alert box, the application uses the Alert function. An 
alert resource with resource ID 128 is passed in a parameter to the Alert function. 

The alert resource in turn specifies an item list resource with resource ID 128. The item 
list resource specifies an OK button, some static text, and an icon, whose resource ID is 
128. (It’s customary to assign the same resource ID to the item list resource and to either 
its alert resource or dialog resource, but it’s not necessary to do so.) 


In this example, when the user chooses the About command, the SurfWriter application 
uses the Alert function to display the alert. 


itemHit := Alert (kAboutBoxID, @MyEventFilter); 





The Alert function in this example displays the alert box defined by the alert resource 
represented by the kAboutBoxID resource ID. As explained in “Responding to Events 

in Alert Boxes” beginning on page 6-81, the Alert function handles most user actions 
while the alert box is displayed. When the user clicks any button in an alert box, Alert 
removes the alert box and returns to your application the item number of the selected 
button. The application-defined function MyEventFilter that is pointed to in this 
example allows background applications to receive update events for their windows. 


Listing 6-5 shows the resources, in Rez input format, that the Alert function uses to 
display the alert box shown in Figure 6-13. 
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Figure 6-13 
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Listing 6-5 


Rez input for providing an alert box with items 


kAboutBoxID 128 
kAboutBoxDITL 128 





kSurfWriterIconID 128 


/*resource ID for About SurfWriter alert box*/ 
/*resource ID for item list*/ 


/*resource ID for 'ICON' resource*/ 


kSurfWriterColorIconID 128 /*resource ID for 'cicn' resource*/ 
kAboutBoxHelp 128 





"ALRT' (kAbout 





{40, 40, 156, 309}, 
kAboutBoxDITL, 
{ /*identical alert stage responses*/ 


OK, 
OK, 
OK, 
OK, 


}, 





visible, 
visible, 
visible, 
visible, 


silent, 
silent, 
silent, 
silent, 


alertPositionMainScreen 
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BoxID, 


/*resource ID for 'hdlg' resource*/ 


purgeable) { /*About SurfWriter alert box*/ 


/*rectangle for alert box*/ 
/*use item list resource with ID 128*/ 


/*display on the main screen*/ 
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resource 'DITL' (kAboutBoxDITL, purgeable) { /*items for About SW alert box*/ 
/*ITEM NO. 1*/ 


{ {86, 201, 106, 259}, /*display rectangle for item*/ 
Button { /*the item is a button*/ 
enabled, /*enable item to return click*/ 
"OK" /*title for button is "OK"*/ 


ly 
/*ITEM NO. 2*/ 


{10;,- 20, 42; 52}, /*display rectangle for item*/ 
Icon { /*the item is an icon*/ 
disabled, /*don't return clicks on this item*/ 


kSurfWriterIconID /*use 'ICON' & 'cicn' resources */ 
/* with resource IDs of 128*/ 
}, 
/*ITEM NO. 3*/ 


{10, 78, 74, 259}, /*display rectangle for the item*/ 
StaticText { /*the item is static text*/ 
disabled, /*don't return clicks on this item*/ 


"SurfWriter 3.0\n"/*text string to display*/ 
"A Swell Text Processor \n\n " 
"©My Company, Inc. 1992" 

}, 

/*ITEM NO. 4*/ 


{0, 0, 0, O}, /*help items get an empty rectangle*/ 

HelpiItem { /*invisible item for reading in help balloons*/ 
disabled, /*don't return clicks on this item*/ 
HMScanhdlg /*scan resource type 'hdlg' for help balloons*/ 


{kAboutBoxHelp} /*get 'hdlg' with resource ID 128*/ 





}; 
data 'ICON' (kSurfWriterIconID, purgeable) { 
/*icon data for black-and-white icon for About SurfWriter goes here*/ 
}; 
data 'cicn' (kSurfWriterColorIconID, purgeable) { 
/*icon data for color icon for About SurfWriter goes here*/ 
}; 


Items are usually referred to by their positions in the item list resource. For example, the 
Alert function returns 1 when the user clicks the OK button in the alert box created in 
Listing 6-5. The Dialog Manager returns 1 because the OK button is the first item in the 
list. (Responding to the item numbers returned by Alert and other Dialog Manager 
functions is explained in “Handling Events in Alert and Dialog Boxes” beginning on 
page 6-77.) Similarly, when you use a Dialog Manager routine to manipulate an item, 
you specify it by its item number, an integer that corresponds to an item’s position in its 
item list resource. 
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IMPORTANT 
Item list resources should always be marked as purgeable. a 


The Dialog Manager also calls the Resource Manager to read in any individual items 
as necessary. 


When you create a dialog box or an alert box, the Dialog Manager creates a dialog record. 
The Dialog Manager then reads in the item list resource and stores a handle to it in the 
items field of the dialog record. Because the Dialog Manager always makes a copy of 
the item list resource and uses that copy, several independent dialog boxes may share 
the same item list resource. As explained in “Adding Items to an Existing Dialog Box” 
beginning on page 6-51, you can use the AppendDITL and ShortenDITL procedures 

to modify or customize copies of a shared item list resource for use in individual 

dialog boxes. 


As an alternative to using a dialog resource, you can read in a dialog’s item list resource 
directly and then pass a handle to it along with other information to NewDialog, which 
creates the dialog box. Remember, however, that it is easier to localize your application if 
you use a dialog resource and the Get NewDialog function. 


An item list resource contains the following information for each item: 
m adisplay rectangle 
m the type of item (as described in the next section) 


m aconstant (either enabledor disabled) that instructs the Dialog Manager whether 
to report events for that item 


m either a text string or a resource ID, as appropriate for the type of item 


The display rectangle determines the size and location of the item. Specify the display 
rectangle in coordinates local to the alert or dialog box. For example, in Listing 6-5 the 
first item is displayed in a rectangle specified by the coordinates (86,201,106,259), which 
place the item in the lower-right corner of this alert box. More information about display 
rectangles and their placement is provided in “Display Rectangles” beginning on 

page 6-32. 


In an item list resource, you can specify controls, text, icons, pictures, and other items 
that you define. In Listing 6-5, the first item’s type is specified by the Button constant. 
Item types and their constants are described in the next section. 


For each item in the item list resource, you must also instruct the Dialog Manager 
whether to report to your application when the item is clicked. In Listing 6-5, the first 
item is enabled, because the enabled constant is specified. “Enabled and Disabled 
Items” on page 6-36 explains when and how to enable items. 


Depending on the type of item in the list, you usually provide a text string or a resource 
ID for the item. In Listing 6-5, the string OK is specified as the button title for the first 
item. “Resource IDs for Items” beginning on page 6-36 explains what titles and resources 
are appropriate for the various item types. 


The information that you provide in an item list resource is described more fully in the 
next several sections. 
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Item Types 


The following list shows the types of items you can include in alert and dialog boxes and 
the constants for specifying them in a Rez input file. 





Constant Description 

Button A button control 

CheckBox A checkbox control (use in dialog boxes only) 

Control A control defined ina 'CNTL' resource file (use in dialog 
boxes only) 

EditText An editable text item (use in dialog boxes only) 

HelpItem An invisible item that makes the Help Manager associate help 


balloons with the other items defined in the item list resource 


Icon An icon whose black-and-white version is stored in an 'ICON' 
resource and whose color version is stored ina 'cicn' resource 
with the same resource ID as the 'ICON' resource 


Picture A QuickDraw picture stored in a 'PICT' resource 
RadioButton A radio button control (use in dialog boxes only) 
StaticText Static text; that is, text that cannot be edited 
UserItem An application-defined item (use in dialog boxes only) 


The chapter “Help Manager” in Inside Macintosh: More Macintosh Toolbox describes how 
to create and use items of type HelpItem to provide help balloons for your alert and 
dialog boxes. When you specify a help item, make it the last item in the list, as shown in 
Listing 6-5 on page 6-27. 


The chapter “Finder Interface” in this book describes icon (' ICON ') resources and color 
icon ('"cicn") resources. Inside Macintosh: Imaging describes 'PICT' resources. 


The chapter “Control Manager” in this book describes how to create a control with 

a 'CNTL' resource. Pop-up menus are easily implemented as controls. “Pop-Up Menus 
as Items” beginning on page 6-42 illustrates how to include pop-up menus in your 
dialog boxes. 


Be aware that alert boxes should contain only buttons (which the user clicks to dismiss 
the alert box), static text, icons, and pictures. If you need to present other items, you 
should create a dialog box. 


The first item in an alert box’s item list resource should be the OK button; if a Cancel 
button is necessary, it should be the second item. The Dialog Manager provides these 
constants for the first two item numbers: 


CONST ok Ass 


cancel = 2; 


As described in “Creating Alert Sounds and Alert Boxes” beginning on page 6-18, you 
define within the alert resource whether the OK or the Cancel button is the default 
button for each alert stage. The Dialog Manager automatically draws a bold outline 
around the button that you specify and, if the user presses the Return key or Enter key, 
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the Dialog Manager responds—or your event filter function should respond—as if the 
default button were clicked. (“Writing an Event Filter Function for Alert and Modal 
Dialog Boxes” beginning on page 6-86 describes event filter functions.) 


The Dialog Manager does not draw a bold outline around the default button for dialog 
boxes. “Using an Application-Defined Item to Draw the Bold Outline for a Default 
Button” beginning on page 6-56 shows how your application can outline the default 
button in a dialog box. You should normally give every dialog box a default button— 
that is, one whose action is invoked when the user presses the Return or Enter key. 
“Writing an Event Filter Function for Alert and Modal Dialog Boxes” beginning on 
page 6-86 shows how to test for these key-down events and respond as if the user had 
clicked the default button. If you don’t provide your own event filter function, the 
Dialog Manager treats the first item in an item list resource as the default button. That is, 
although the Dialog Manager doesn’t draw a bold outline around the button in a dialog 
box, the Dialog Manager does return its item number to your application when the user 
presses the Return or Enter key. 


Don’t set a default button to perform a dangerous action—for example, one that causes 

a loss of user data. If none of the possible actions is safe, don’t display a default border 
around any button and provide an event filter function that ignores the Return and Enter 
keys. This protects users from accidentally damaging their work by pressing Return or 
Enter out of habit. However, you should try to design a safe action that the user can 
invoke with a default button, such as a Save button. Figure 6-14 illustrates an alert box 
that provides a default button for a safe action. 


Figure 6-14 A safe default button in an alert box 
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Provide a Cancel button whenever you can, and in your event filter function, map the 
Command-period key combination and the Esc (Escape) key to the Cancel button. 


Don’t display a bold outline around any button if you use the Return key in editable text 
items, because using the same key for two different purposes confuses users and makes 
the interface less predictable. 
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Display Rectangles 


As previously mentioned, the display rectangle determines the location of an item 
within an alert box or a dialog box. Use the alert or dialog box’s local coordinates to 
specify the display rectangle. 


For controls, the display rectangle becomes the control’s enclosing rectangle. To match 

a control’s enclosing rectangle to its display rectangle, specify an enclosing rectangle 

in the control resource that is identical to the one you specify for the display rectangle in 
the item list resource. (The control resource is described in the chapter “Control 
Manager” in this book.) 


Note 

Note that, when an item is a control defined in a control ('CNTL") 
resource, the rectangle added to the update region is the rectangle 
defined in the control resource, not the display rectangle defined in 
the item list resource. @ 


For an editable text item, the display rectangle becomes the TextEdit destination 
rectangle and its view rectangle. Word wrapping occurs within display rectangles that 
are large enough to contain multiple lines of text, and the text is clipped if there’s more 
than will fit in the rectangle. The Dialog Manager uses the QuickDraw procedure 
FrameRect to draw a rectangle three pixels outside the display rectangle. For more 
detailed information about TextEdit, see the chapter “TextEdit” in Inside Macintosh: Text. 


For a static text item, the Dialog Manager draws the text within the display rectangle just 
as it draws editable text items, except that the Dialog Manager doesn’t draw a frame 
rectangle outside the display rectangle. 


For an icon or a QuickDraw picture larger than its display rectangle, the Dialog Manager 
scales the icon or picture to fit the display rectangle. 


Although the procedure for an application-defined item can draw outside the item’s 
display rectangle, this is not recommended, because if the Dialog Manager receives 
an update event involving an area outside the display rectangle but inside the area 
where you draw your application-defined item, the Dialog Manager won’t call your 
draw procedure. 


Note 

A click anywhere in the display rectangle is considered a click in that 
item. If display rectangles overlap, a click in the overlapping area 

is considered a click in whichever item appears first in the item list 
resource. 


You should display items in functional and consistent locations, both within your 
application and across all applications that you develop. In alert boxes and in most 
dialog boxes, place the OK button in the lower-right corner and place the Cancel 
button to its left. Figure 6-15 shows the recommended location of buttons and text 
in an alert box. 
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Figure 6-15 The consistent spacing of buttons and text in an alert box 
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Generally, you should use distances of 13 and 23 white pixels to separate the items in 
dialog boxes and alert boxes. (When separating the default button from the window 
edges and other items, don’t count the pixels that make up its bold outline.) However, be 
aware that the Window Manager adds 3 white pixels inside the window frame when it 
draws alert boxes and modal dialog boxes. Therefore, specify display rectangle locations 
as follows when you use tools like Rez and ResEdit: 


m Place the display rectangle for the lower-right button 10 pixels from the right edge 
and 10 pixels from the bottom edge of the alert or modal dialog box; align the display 
rectangles for other bottommost and rightmost items with this button. 


m Place the display rectangle for the upper-left icon (or similar item) 10 pixels from the 
top edge and 20 pixels from the left of the alert or modal dialog box; align the display 
rectangles for other topmost and leftmost items with this item. The Dialog Manager 
automatically places the caution, note, and stop alert icons in this position when you 
use the CautionAlert, NoteAlert, and StopAlert functions. When you use the 
Alert function, you must specify the icon and the location. 


m Place the other elements in the alert or modal dialog box 13 or 23 pixels apart, as 
shown in Figure 6-15. 


For example, the rectangle for the alert box in Figure 6-15 has a specified height of 

85 pixels. The display rectangle for the Save button has a bottom coordinate of 75, and 
the display rectangle for the static text item has a top coordinate of 10. The Window 
Manager adds 3 white pixels at the top of the alert box and 3 pixels at the bottom, so 
the alert box contains 13 white pixels below the Save button and 13 white pixels above 
the static text display rectangle. Listing 6-6 shows how the locations for these display 
rectangles are specified in a Rez input file. 


Using the Dialog Manager 6-33 


6-34 


CHAPTER 6 


Dialog Manager 


Listing 6-6 Rez input for consistent spacing of display rectangles 


resource 'DITL' (200, purgeable) { 


{ {55, 288, 75, 348}, Button {enabled, "Save"}, 
{55, 215, 75, 275}, Button {enabled, "Cancel"}, 
{55, 72, 75, 156}, Button {enabled, "Don't Save"}, 


{10, 75, 42, 348}, StaticText {disabled, 
"Save changes to the SurfWriter document “*0” before" 


" closing?"} 


}; 


When specifying display rectangle locations for items in movable modal and modeless 
dialog boxes, use the full distance of either 13 or 23 pixels to separate items from the 
window edges. For example, if the items in Figure 6-15 were placed in a modeless dialog 
box, the top coordinate of the Save button’s display rectangle should be 52 instead of 55, 
and its bottom coordinate would be 72 instead of 75. 


As explained in the previous section, the default button can be any button; its assign- 
ment is secondary to the consistent placement of buttons. This rule keeps the OK button 
and the Cancel button consistently placed. Otherwise, the buttons would keep changing 
location depending on the default choice. 


The Western reader’s eye tends to move from the upper-left area of the alert or dialog 
box to the lower-right area. For Western versions of your software, use the upper-left 
area for elements (such as the alert icon) that convey the initial impression that you want 
to make. Place the buttons that a user clicks in the lower-right area. 


The alignment of the items in an alert box or a dialog box may vary with localization. 
Although in Roman script systems these items are generally aligned left to right, items 
in Arabic or Hebrew script systems should generally be aligned right to left, because 
Arabic and Hebrew are written from right to left. The TextEdit procedure TESet Just, 
described in the chapter “TextEdit” in Inside Macintosh: Text, controls the alignment of 
interface elements. 





When line alignment is right to left, as in Hebrew and Arabic, the Control Manager 
transposes checkboxes—and radio buttons—and their titles. That is, checkboxes and 
radio buttons appear to the right of the text instead of to the left, as in Roman script 
systems. Therefore, when you create checkboxes, radio buttons, and static text items 
that need to align, make sure that their display rectangles are the same size. 


The dialog box at the top of Figure 6-16 shows several checkboxes and radio buttons 
with display rectangles of different sizes. The next dialog box in the figure illustrates 
what happens to the alignment of these items after the Control Manager transposes 
the controls with their titles. 


The bottom two dialog boxes in Figure 6-16 illustrate how the Control Manager displays 
properly sized items when transposing the controls with their titles. 
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Figure 6-16 Incorrectly and correctly sized display rectangles for alternate script systems 
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Enabled and Disabled Items 


For each item in an item list resource, include one of these two constants to specify in a 
Rez input file whether the Dialog Manager should inform your application of events 
involving that item: 


Constant Description 
enabled Informs your application about events involving this item 
disabled Doesn’t inform your application about events involving this item 


Generally, you should enable only controls. In particular, you should enable buttons, 
radio buttons, and checkboxes so that your application knows when they’ve been 
clicked. You typically disable editable text and static text items. You normally disable 
editable text items because you use the Dialog Manager function GetDialogItemText 
to read the information in the items only after the user clicks the OK button. (Listing 6-12 
on page 6-49 illustrates how to use the GetDialogItemText function for this purpose.) 
You should use static text items only for providing information; users don’t expect to 
click them. Likewise, you typically disable icons and pictures that merely provide 
information; if you use an icon or a picture as a buttonlike control to receive input, 
however, you must enable it. If you create an application-defined item such as a moving 
indicator to display information, you typically disable it. If you create an application- 
defined item such as a buttonlike control to receive input, you must enable it. 


Don’t confuse disabling an item with using the Control Manager procedure 
HiliteControl to make a control inactive. When you don’t want the Control Manager 
to respond to clicks in a control, you make it inactive; when you don’t want the Dialog 
Manager to report clicks in a control, you make it disabled. 


The Control Manager displays an inactive control in a way (dimmed, for example) that 
shows it’s inactive, whereas the Dialog Manager makes no visual distinction between a 
disabled item and an enabled item. Figure 6-17 shows the difference between an inactive 
and an active control. The Control Manager procedure HiliteControl has been used 
to dim the inactive Eject button. If a user clicks this button, the Control Manager does 
not respond. However, when a user clicks the active Desktop button, the Control 
Manager inverts the button for 8 ticks. 


Buttons and other controls are generally enabled, and disabling them does not alter their 
appearance; the enabled radio button in Figure 6-17 would appear the same if it were 
disabled. Because the static text reading “Save this document as” in Figure 6-17 is not 

a control, the application doesn’t need to respond clicks in the text. Therefore, the 
application has disabled it; however, the static text would have the same appearance 

if the application were to enable it. 


Resource IDs for Items 


The final element for an item in an item list resource is usually either a text string or a 
resource ID. The choice depends on the type of item. 
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Figure 6-17 Inactive controls and disabled items 
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Provide a resource ID for icons, QuickDraw pictures, and controls other than buttons, 
checkboxes, and radio buttons. For an icon, provide the ID of an ' ICON" resource; for 

a QuickDraw picture, the ID of a 'PICT' resource; and for a control (including a pop- 
up menu), the ID of a 'CNTL' resource. In Listing 6-5 on page 6-27, the resource ID of 
128 specifies which 'ICON' (and 'cicn"') resources to use for the second item in the 
item list resource. 


For a button, checkbox, radio button, static text item, and editable text item, supply a text 
string as the final element for the item in its item list resource. The next several sections 
provide guidelines for the text that you should provide. 


For your own application-defined items, supply neither a title nor a resource ID. 
Listing 6-15 on page 6-57 shows an item list resource that includes an application- 
defined item. 


Titles for Buttons, Checkboxes, and Radio Buttons 


For a button, checkbox, or radio button, provide a text string for the control’s title as the 
final element for the item when you specify it in the item list. In Listing 6-5 on page 6-27, 
the string OK specifies the button title for the first item in the item list resource. 


Use book-title capitalization for these items. In general, this means that you capitalize 
one-word titles and, in multiple-word titles, words of four or more letters. Usually you 
don’t capitalize words such as in, an, or and. The rules for capitalization of titles appear 
in the Apple Publications Style Guide, which is available from APDA. 


As explained in the chapter “Control Manager” in this book, the title of a checkbox 
should reflect two clearly opposite states, because a checkbox should allow the user to 
turn a particular setting either on or off. The opposites should be expressed in an equal 
sense in either state. If you can’t devise a checkbox title that clearly implies its opposite 
state, you might be better off using radio buttons. With radio buttons, you can use two 
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titles, thereby clarifying the states. Radio buttons should represent related, but not 
necessarily opposite, choices. Give each radio button a title consisting of a word or a 
phrase that identifies what the button does. Remember that, as described in the chapter 
“Control Manager” in this book, the radio buttons in a group are mutually exclusive: 
only one button in that group can be on at one time. 


Wherever possible, title a button with a verb describing the action that the button 
performs. A user typically reads the text in an alert box or a dialog box until it becomes 
familiar and then relies on visual cues, such as button titles or positions, to respond. 
Buttons such as Save, Quit, or Erase Disk allow users to identify and click the correct 
button quickly. These titles are often more clear and precise than OK, Yes, and No. If the 
action can’t be condensed into a word or two, OK and Cancel or Yes and No may serve 
the purpose. If you use these generic titles, be sure to phrase the wording in the dialog 
box so that the action the button initiates is clear. Figure 6-18 shows a dialog box with 
appropriate OK and Cancel buttons. 


Figure 6-18 A dialog box with OK and Cancel buttons 
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Cancel means “dismiss this operation with no side effects.” It does not mean “I’ve read 
this dialog box” or “stop what you’re doing regardless.” When users click the Cancel 
button in your alert boxes, modal dialog boxes, and movable modal dialog boxes, your 
application should revoke any actions it took since displaying the alert or dialog box and 
then remove the box. 


Your application should not remove a modeless dialog box when the user clicks a 
button; rather, you should remove the dialog box when the user clicks its close box or 
chooses Close from the File menu while the modeless dialog box is active. 


When it is impossible to return to the state that existed before an operation began, don’t 
use a Cancel button. You can use Stop or OK, which are useful in different situations. A 
Stop button may leave the results of a partially complete task intact, whereas a Cancel 
button always returns the application and its documents to their previous state. Use OK 
for a button that closes the alert box, modal dialog box, or movable modal dialog box 
and accepts any changes made while the dialog box was displayed. 


Because of the difficulty in revoking the last action invoked from a modeless dialog box, 
these dialog boxes typically don’t have Cancel buttons, although they may have Stop 
buttons. For example, the movable modal dialog box shown in Figure 6-19 uses a Stop 


Using the Dialog Manager 


CHAPTER 6 


Dialog Manager 


button; clicking the button halts the current file copy operation but leaves intact the 
copies that were previously made. 


Figure 6-19 A movable modal dialog box with a Stop button 
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In an alert box that requires confirmation, use a button title that describes the result of 
accepting the message in the alert box. For example, if an alert box asks “Revert to the 
last saved version of the document,” use a Revert button rather than an OK button. Try 
to use a verb in the button title; as in the Revert button in Figure 6-20, use the same verb 
that you use in your alert message. 


Figure 6-20 An alert box with a Revert button 





i Revert to the last saved version of the 


SurfWriter document “My Window”? 





If the alert box presents the user with a situation in which no alternative actions are 
available, give the box a single button that’s titled OK. You should interpret the user’s 
clicking this button to mean “I’ve read the alert box.” 


A modal dialog box usually cuts the user off from the task. That is, when making choices 
in a modal dialog box, the user can’t see the area of the document that changes. The user 
sees the changes only after dismissing the dialog box. If the changes aren’t appropriate, 
then the user has to repeat the entire operation. To provide better feedback to the user, 
you need to give the user a way to see what the changes will be. Therefore, any selection 
made in a modal dialog box should immediately update the document contents, or you 
should provide a sample area in the dialog box that reflects how the user’s selections 
will change the document. In the case of immediate document updating, the OK button 
means “accept this change” and the Cancel button means “undo all changes made 
through this dialog box.” 


The Dialog Manager displays button titles (as well as all other control titles) in the 
system font. To make it easier to localize your application, you should not change 
the font. 
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Text Strings for Static Text and Editable Text Items 


For an editable text item, if you want the item to display only a blinking cursor, specify 
an empty string as the item’s final element in the item list resource or specify a string if 
you want to display some default text. 


For a static text item, supply a text string as its final element when you specify it in the 
item list resource. In the third item in Listing 6-5, the text string SurfWriter 3.0 
\nA Swell Text Processor \n\n©My Company, Inc. 1992 specifies the alert 
box’s message. 


Whenever you provide static text items in alert and dialog boxes, ensure that the 
messages make sense to the user. Use simple, nontechnical language and don’t provide 
system-oriented information to which the user can’t respond. 


Whenever applicable, state the name of the document or application in your alert or 
dialog box. For example, the alert box in Figure 6-20 on page 6-39 shows both the name 
of the application (SurfWriter) and the name of the document (My Window). This kind 
of message helps users who are working with several documents or applications at once 
to make decisions about each one individually. “Changing Static Text” beginning on 
page 6-46 describes how to use the ParamText procedure to supply the names of 
document windows to your alert and dialog boxes dynamically. 


Use icons and pictures whenever possible. Images can describe some error situations 
better than words, and familiar icons help users distinguish their alternatives better. 
However, because experience has shown that it is nearly impossible to create icons that 
are comprehensible or inoffensive across all international markets, you should be 
prepared to localize any icons or pictures you use. See the chapter “Icons” in Macintosh 
Human Interface Guidelines for more information about creating appropriate icons. 


For your static text items, it’s generally better to be polite than abrupt, even if it 
means lengthening your message. Your message should be helpful, and it may offer 
constructive suggestions, but it should not appear to give orders. Its focus should be 
to help the user perform the task, not to give an interesting but academic description 
of the task itself. 


When you localize your application for use with other languages, the text may become 
longer or shorter. Translated text is often 50 percent longer than U.S. English text. You 
may need to resize your display rectangles and your alert and dialog boxes to 
accommodate the translated text. 


By default, the Dialog Manager displays static text items in the system font. To make it 
easier to localize your application, you should not change the font. Do not use a smaller 
font, such as 9-point Geneva; some script systems such as KanjiTalk require 12-point 
fonts. You will save yourself future localization effort by leaving all the text in your alert 
and dialog boxes in the system script. 


In alert boxes, try to include information that tells the user how to resolve the problem at 
hand. Never refer the user to external documentation for further clarification. 


Stop alerts typically report errors to the user. A good error message explains what 
went wrong, why it went wrong, and what the user can do about it. Express this 
information in the user’s vocabulary, not in your programming vocabulary. 
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Figure 6-21 shows an example of a very poor alert message—the information is 
expressed in the programmer’s vocabulary, and the user is offered no clue about 
how to remedy the problem. 


Figure 6-21 An obscure and useless alert message 





© Buffer overflow (error #6/28) 





Figure 6-22 shows a somewhat better alert message. Although the vocabulary is less 
technical, no remedy to the problem is offered. 


Figure 6-22 A less obscure alert message 


i) Too much tent for this field. 








Figure 6-23 illustrates a good alert message. The message is specific, it’s expressed in 
nontechnical terms, it explains why the error occurred, and it suggests a solution to 
the problem. 


Figure 6-23 A clear and helpful alert message 





The street address must be less than 50 
characters long to fit on the envelope. 
Try abbreviating common words. 





The best way to make an alert message understandable is to think carefully through the 
error condition itself. Can the application handle this without an error? Is the message 
specific enough so that the user can fix the situation? What are the recommended 
solutions? 
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Pop-Up Menus as Items 


You can use pop-up menus to present the user with a list of mutually exclusive choices 
in a dialog box. Figure 6-24 illustrates a typical use of pop-up menus in a dialog box. As 
explained in the chapter “Control Manager” in this book, pop-up menus are especially 
useful as an alternative to radio buttons when the user must make one choice from a list 
of many or set a specific value, or when you must present a variable list of choices. The 
pop-up menu in Figure 6-24 allows the application to present a choice of modem speeds 
that vary according to the modem type in the user’s computer. 


Figure 6-24 A pop-up menu in a dialog box 
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In System 7, pop-up menus are implemented as controls. To display a pop-up menu ina 
dialog box, you 


m define specific features of the pop-up menu in a control that uses the standard pop-up 
control definition function (described in the chapter “Control Manager” in this book) 


m define the menu items of a pop-up menu just as you define items in other menus 
(using GetMenu or NewMenu, as described in the chapter “Menu Manager” in 
this book) 





m specify the pop-up menu in the dialog box’s item list resource 


Using the pop-up control definition function, the Dialog Manager automatically draws 
the pop-up box and its drop shadow, inserts the text into the pop-up box, draws a 
downward-pointing triangle, and draws the pop-up menu’s title. When the user moves 
the cursor to a pop-up menu and presses the mouse button, the pop-up control 
definition function highlights the pop-up menu title, displays the pop-up menu, and 
handles all user interaction until the user releases the mouse button. When the user 
releases the mouse button, the pop-up control definition function closes the pop-up box, 
draws the user’s choice in the pop-up box (or restores the previous item if the user 
doesn’t make a new choice), and removes the highlighting from the pop-up menu title. 
The control definition function then sets the value of the control to the item selected by 
the user. Your application can use the Control Manager function Get Cont rolValue 
to get the number of the currently selected item. 
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The modal dialog box shown in Figure 6-24 is created by defining a dialog resource that 
describes the dialog box and by defining an item list resource that describes the dialog 
items, including a control whose 'CNTL" resource uses the standard pop-up control 
definition function. Listing 6-7 shows the dialog resource and item list resource for this 
modal dialog box. 


Listing 6-7 Rez input for a dialog resource and an item list resource for a dialog box that 
includes a pop-up menu 


"DLOG' (kModemDialog, purgeable) { 


{62, 184, 216, 416}, dBoxProc, visible, noGoAway, 0x0, 
kModemDialogDITL, "", alertPositionMainScreen 





resource 'DITL' (kModemDialogDITL, purgeable) { 
{ {123, 152, 144, 222}, Button {enabled, "OK"}, 
{123, 69, 144, 139}, Button {enabled, "Cancel"}, 
(30 [107 335° 2044 x StaticText {enabled, "Modem Setup"}, 
{41, 23, 61, 64}, StaticText {enabled, "Port:"}, 
{41, 67, 59, 186}, RadioButton {enabled, "Modem Port"}, 
{59, 67, 77, 186}, RadioButton {enabled, "Printer Port"}, 
{90,18,109,198}, Control {disabled, kPopUpCNTL}, 
{123, 152, 144, 222}, UserItem {disabled} /*outline OK button*/ 
£.0::0;:0:,°0}.7 HelpItem {disabled, HMScanhdlg{kModemHelp} } 
/*Balloon Help*/ 
} 
}; 
Listing 6-8 shows the 'CNTL' and 'MENU' resources for the Speed pop-up menu shown 
in Figure 6-24. Notice that the display rectangle specified for the control in the item list 
resource is the same as the enclosing rectangle specified in the control resource. See the 
chapter “Control Manager” in this book for a complete description of how to specify 
values for a pop-up menu’s control resource. 
Listing 6-8 Rez input for a control resource and a menu resource for a pop-up menu 
resource 'CNTIL' (kPopUpCNTL, preload, purgeable) { 
{90, 18, 109, 198}, /*enclosing rectangle of control*/ 
popupTitleLeftJust, /*title position*/ 
visible, /*make control visible*/ 
50, /*pixel width of title*/ 
kPopUpMenu, /*"MENU' resource ID*/ 
popupMenuCDEFProc, /*pop-up control definition ID*/ 
0, /*reference value*/ 
"Speed:" /*control title*/ 


}; 
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ource 'MENU' (kPopUpMenu, preload, purgeable) { 

mPopUp, textMenuProc, 

0b1111111111111111111111111111111, 

enabled, "Speed", 

{ 
"300 bps", noicon, nokey, nomark, plain; 
"1200 bps", noicon, nokey, nomark, plain; 
"2400 bps", noicon, nokey, nomark, plain; 
"9600 bps", noicon, nokey, nomark, plain; 
"19200 bps", noicon, nokey, nomark, plain 


Keyboard Navigation Among Items 


Your dialog boxes may have several items, such as editable text items and scrolling lists, 
that can accept input from the keyboard. You need to give users a visual cue indicating 
which item is currently accepting input from the keyboard. Each item type has its own 
distinct indicator. The Dialog Manager automatically displays a blinking cursor in an 
editable text item to indicate that it is accepting keyboard input. You can also use the 
SelectDialogItemText procedure (explained on page 6-131) to indicate a selected 
text range within an editable text item. 


When a scrolling list is accepting keyboard input, you should indicate it by a rectangular 
border of two black pixels, separated from the list by one pixel of white space. In 

Figure 6-25, the AppleTalk Zones scrolling list is the item currently accepting keyboard 
input in the Chooser dialog box. See the chapter “List Manager” in Inside Macintosh: 
More Macintosh Toolbox for details about creating lists in dialog boxes. 


Because all typing goes to the active window, there should be only one active area and 
only one indicator at any time. If only one element in a dialog box can accept keyboard 
input and that element is a scrolling list, it’s not necessary to place a border around it. 


The Dialog Manager automatically handles mouse-down events and keyboard events 
for the Tab key. Thus, the user can select any item that accepts keyboard input by 
clicking the desired item or by pressing the Tab key to cycle through the available items. 
When the user presses the Tab key, the Dialog Manager accepts the changes made to the 
current item and selects the next item—as listed in the item list—that accepts keyboard 
input. When the user clicks another item, the Dialog Manager accepts the changes made 
to the current item and selects the newly clicked item. 


Manipulating Items 


In many cases, you won't have to make any changes to alerts or dialog boxes after you 
define them in your resource file. However, if you should want to modify an item, you 
can use several Dialog Manager routines to do so. 
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Figure 6-25 A selected scrolling list 
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For example, you can use the ParamText procedure to supply text strings (such as 
document titles) to alert and dialog boxes dynamically. For most other types of item 
manipulation, you must first call the GetDialogItem procedure to get the information 
about the item. You then use other routines to manipulate that item. For example, you 
can use the SetDialogItem procedure to change the item, or—to get a text string that 
the user has entered in an editable text item after clicking the OK button—you can use 
the GetDialogItemText procedure. 


The Dialog Manager routines for manipulating items are summarized in the 


following list. 


Routine 
AppendDITL 
CountDITL 
FindDialogItem 


GetAlertStage 
GetDialogItem 
GetDialogItemText 


HideDialogItem 


ParamText 


ResetAlertStage 
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Description 
Adds items to a dialog box. 
Counts the number of items in a dialog box. 


Finds an item that contains a specified point within a 
dialog box. 


Returns the stage of the last occurrence of an alert. 


Returns the item type, the display rectangle, and the 
control handle or application-defined procedure of a 
given item in a dialog box. 


Returns the text of a given editable text or static 
text item. 


Hides the given item. 


Substitutes up to four different text strings in static 
text items. 


Resets the stage of the last occurrence of an alert. 
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Routine Description 

SelectDialogItemText Selects the text of an editable text item. 

SetDialogItem Sets the item type and the display rectangle of an item, 
or (for application-defined items) the draw procedure 
of an item. 

ShortenDITL Removes items from a dialog box. 

ShowDialogItem Redisplays the item previously hidden by 
HideDialogItem. 


The next several sections describe the most frequently used of these routines. The next 
section, “Changing Static Text,” explains the use of the ParamText procedure to 
manipulate the text in static text items. “Getting Text From Editable Text Items” 
beginning on page 6-48 describes how to use the GetDialogItemText procedure 

to determine what the user types in an editable text item. Using the AppendDITL 
procedure is explained in “Adding Items to an Existing Dialog Box” beginning on 
page 6-51. “Using an Application-Defined Item to Draw the Bold Outline for a Default 
Button” beginning on page 6-56 describes how to use SetDialogItem to install 
application-defined items. For additional information about all of the previously listed 
routines, see “Manipulating Items in Alert and Dialog Boxes” beginning on page 6-120 
and “Handling Text in Alert and Dialog Boxes” beginning on page 6-129. 


Changing Static Text 


As previously explained, it is often useful to state the name of a document in an alert box 
or a dialog box. For example, Figure 6-26 shows an alert box that an application might 
display when the user closes a window that contains unsaved changes. 


Figure 6-26 An alert box that displays a document name 





A Save changes to the SurfWriter document 


“My Window” before closing? 





You can use the ParamText procedure to supply the names of document windows to 
your alert and dialog boxes dynamically, as illustrated in the application-defined routine 
MyCloseDocument shown in Listing 6-9. 
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Listing 6-9 Using the ParamText procedure to substitute text strings 


PROCEDURE MyCloseDocument (myData: MyDocRecHnd) ; 
VAR 

title: Stxr255; 

item: Integer; 





docWindow: WindowPtr; 


event: EventRecord; {dummy parameter for calling DialogSelect} 
myErr: OSErr; 

BEGIN 
docWindow := FrontWindow; {point to active window} 


IF (myData**.windowDirty) THEN {document has been changed} 
BEGIN 
GetWTitle(docWindow, title); {get title of window} 
MyStringCheck (title); 


ParamText (title, '', '', ''); {pass the title in lst parameter} 
DoActivate(docWindow, FALSE, event); {deactivate the active window} 
item := CautionAlert (kSaveAlertID, @MyEventFilter); {display alert box} 


IF item = kCancel THEN 
Exit (MyCloseDocument) ; 
IF item = kSave THEN 


DoSaveCmd; {save the document} 
myErr := DoCloseFile(myData) ; {close the file} 
END; {let click in Don't Save fall through} 


CloseWindow (docWindow) ; 
DisposPtr (Ptr (docWindow) ) ; 
END; 





In this example, the Window Manager function Front Window returns a pointer to 

the active window. Another Window Manager function, GetWTit1le, returns the title 
of that window. The MyCloseDocument routine passes this string to the ParamText 
procedure, which takes four text strings as parameters. In this example, only one string 
is needed (the window title), which is passed in the first parameter; empty strings are 
passed for the remaining three parameters. 


You can use ParamText to supply up to four text strings for a single alert or dialog box. 
In the item list resource for the alert or dialog box, specify where each of these strings 
should go by inserting the special characters *0 through “3 in any of the items where 
you can specify text. The ParamText procedure dynamically replaces “0 with the string 
you pass in its first parameter, “1 with the string in the second parameter, and so forth, 
when you display the alert or dialog box. 
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IMPORTANT 

To avoid recursion problems in versions of system sofware earlier than 
7.1, you have to ensure that you do not include the characters *0 
through *3 in any strings you pass to ParamText. This is why 
MyCloseDocument uses another application-defined routine, 
MyStringCheck, to filter these characters out of the window titles 
passed toParamText. A 


Listing 6-10 shows a portion of an item list resource. When the application calls 
CautionAlert, the Dialog Manager uses the first parameter passed previously to the 
ParamText procedure to replace the characters *0 in the static text with the title of the 
document window. 


Listing 6-10 Specifying where ParamText should substitute text in an alert box message 


resource 'DITL' (kSaveAlertID, purgeable) { 


hi 


6-48 


{ 


/*Save button information goes here*/ 
/*Cancel button information goes here*/ 
/*Don't Save button information goes here*/ 
{10, 75, 42, 348}, 
StaticText { /*ask the user to save changes to the document--*/ 
disabled, /* filename inserted with ParamText*/ 





"Save changes to the SurfWriter document “*0” before closing?" 


}, 
/*help item information goes here*/ 


Getting Text From Editable Text Items 


The application displaying the modeless dialog box shown in Figure 6-27 uses the 
GetDialogItem and GetDialogItemText procedures after the user clicks the 
Change button. 


Figure 6-27 Two editable text items in a modeless dialog box 





= Global Changes 








Using the Dialog Manager 


CHAPTER 6 


Dialog Manager 


This dialog box prompts the user for two text strings: one to search for and another 

to take the place of the first string. Listing 6-11 shows the item list resource for this 
dialog box. The fifth item in the list is the editable text item where the user enters the text 
string being sought; the sixth item is the item where the user enters the replacement 

text string. 


Listing 6-11 Specifying editable text items in an item list 


resource 'DITL' (kGlobalChangesDITL, purgeable) { 




















{ /*ITEM NO. 1*/ 
{70, 213, 90, 271}, Button {enabled,"Change"}, 
/*ITEM NO. 2*/ 
{70, 142, 90, 200}, Button {enabled,"Stop"}, 
/*ITEM NO. 3*/ 
{107 23,5: 277 985 StaticText {disabled, "Find What:"}, 
/*ITEM NO. 4*/ 
(40, -23,. ST, 98°}, StaticText {disabled,"Change To:"}, 
/*ITEM NO. 5*/ 
{10, 117, 27, 271}, EditText {disabled, ""}, 
/*ITEM NO. 6*/ 
{40, 117, 57, 271}, EditText {disabled, ""} 
/*ITEM NO. 7: for drawing outline around Change button*/ 
{63, 205, 97, 278}, UserItem {disabled, }, 
/*ITEM NO. 8: help item goes here*/ 








hi 


Listing 6-12 shows how the application handles a click in the Change button. 
(Subsequent sections of this chapter explain how to handle events in a modeless 
dialog box.) 


Listing 6-12 Getting the text entered by the user in an editable text item 


PROCEDURE MyHandleModelessDialogs (theEvent: EventRecord) ; 
VAR 

myDialog: DialogPtr; 

itemHit, itemType: Integer; 

searchStringHandle: Handle; 

replaceStringHandle: Handle; 


searchString: Str255; 
replaceString: Str255; 
itemRect: Rect; 
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BEGIN 
{use DialogSelect, then determine whether the event occurred } 








{ in the Global Changes dialog box; if so, respond to mouse } 
{ clicks as follows} 
CASE itemHit OF 
kChange: {user clicked the Change button} 
BEGIN 
GetDialogItem(myDialog, kFind, itemType, 





searchStringHandle, itemRect) ; 
GetDialogItemText (searchStringHandle, searchString) ; 
GetDialogItem(myDialog, kReplace, itemType, 
replaceStringHandle, itemRect); 
GetDialogItemText (replaceStringHandle, replaceString) ; 
{get a handle to the Stop button} 
GetDialogItem(myDialog, kStop, itemType, 








itemHandle, itemRect) ; 
{make the Stop button active during the operation} 
HiliteControl (ControlHandle(itemHandle), 0); 
{get a handle to the Change button} 
GetDialogItem(myDialog, kChange, itemType, 
itemHandle, itemRect) ; 
{make the Change button inactive during the operation} 
HiliteControl (ControlHandle(itemHandle), 255); 
DoReplace(searchString, replaceString) ; 
{when the operation is complete, dim Stop and make } 
{ Change active here} 


END; 
kStop: {user clicked the Stop button} 

BEGIN 
{cancel operation, then make Stop button } 
{ inactive and Change button active again} 

END; 

END; 
END; 


In Listing 6-12, when the user clicks the Change button, the GetDialogItem procedure 
returns a handle to the item containing the search string. Because this is a handle to an 
editable text item, the application can pass the handle to the GetDialogItemText 
procedure, which then returns the item’s text string in its second parameter. These two 
procedures are then used to get the string in the item containing the replacement string. 
These two strings are then passed to an application-defined routine that replaces all 
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instances of the first string with the characters of the second string. Note that when the 
user clicks Change, the Control Manager procedure HiliteControl is used to make 
the Stop button active and to make the Change button inactive—that is, dimmed. This 
indicates that the user can use the Stop button but not the Change button while the 
change operation is taking place. 


Adding Items to an Existing Dialog Box 


You can dynamically add items to and remove items from a dialog box by using the 
AppendDITL and ShortenDITL procedures. When you create a dialog box, the Dialog 
Manager creates a dialog record. The Dialog Manager then reads in the item list resource 
and stores a handle to it in the items field of the dialog record. Because every dialog 
box you create has its own dialog record, you can define dialog boxes whose items are 
defined by the same item list resource. The AppendDITL and ShortenDITL procedures 
are especially useful if several dialog boxes share the same item list resource and you 
want to add or remove items as appropriate for individual dialog boxes. 


When you call the AppendDITL procedure, you specify a dialog box, and you specify a 
new item list resource to append to the dialog box’s existing item list resource. You also 
specify where the Dialog Manager should display the new items. You can use one of 
these constants to designate where AppendDITL should display the appended items: 


CONST overlayDITL = 0; {overlay existing items} 
appendDITLRight 
appendDITLBottom = 2; {append at bottom} 

TYPE DITLMethod = Integer; 


ll 
hh 
~ 


{append at right} 








Figure 6-28 illustrates an existing dialog box and a pair of items to be appended. 


Figure 6-28 An existing dialog box and items to append 
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Initial dialog box ltems to be appended 
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If you specify the overlayDITL constant, AppendDITL superimposes the appended 
items over the dialog box. That is, AppendDITL interprets the coordinates of the display 
rectangles for the appended items (as specified in their item list resource) as local 
coordinates within the dialog box. Figure 6-29 shows the result of overlaying the items 
upon the dialog box illustrated in Figure 6-28. 


Figure 6-29 The dialog box after items are overlaid 
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If you specify the appendDITLRight constant, AppendDITL appends the items to the 
right side of the dialog box, as illustrated in Figure 6-30, by positioning the display 
rectangles of the appended items relative to the upper-right coordinate of the dialog box. 


The AppendDITL procedure automatically expands the dialog box to accommodate the 
new dialog items. 


Figure 6-30 The dialog box after items are appended to the right 
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If you specify the appendDITLBottom constant, AppendDITL appends the items to the 
bottom of the dialog box, as illustrated in Figure 6-31, by positioning the display 
rectangles of the appended items relative to the lower-left coordinate of the dialog box. 


The AppendDITL procedure automatically expands the dialog box to accommodate the 
new dialog items. 


Using the Dialog Manager 


CHAPTER 6 


Dialog Manager 


Figure 6-31 The dialog box after items are appended to the bottom 
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As an alternative to passing the overlayDITL, appendDITLRight, or 
appendDITLBottom constant, you can pass a negative number to AppendDITL, which 
appends the items relative to an existing item in the dialog box. The absolute value of 
this number is interpreted as the item in the dialog box relative to which the new items 
are to be positioned. For example, if you pass —2 to AppendDITL, the display rectangles 
of the appended items are offset from the upper-left corner of item number 2 in the 
dialog box. Figure 6-12 on page 6-24 shows a simple dialog box with two checkboxes. 
Figure 6-32 shows the same dialog box after an additional item is appended relative to 
the first checkbox, so that the new item appears between the two existing checkboxes. 





Figure 6-32 A dialog box with an item appended relative to an existing item 





WipeOut typing correction options: 


CJ Ignore Words in All Caps 
CJ Include Spanish Dictionary 


CJ Ignore Slang Terms 








The application-defined routine called DoSpel11BoxWithSpanish, which is shown in 
Listing 6-13 on the next page, illustrates the use of the AppendDITL procedure to add 
the new item. 
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Listing 6-13 Appending an item to an existing dialog box 


FUNCTION DoSpellBoxWithSpanish: OSErr; 
VAR 
theDialog: DialogPtr; 





myNewlItem: Handle; 
docWindow: WindowPtr; 
event: EventRecord; 
BEGIN 

theDialog := GetNewDialog(kSpellCheckID, NIL, Pointer(-1)); 
IF theDialog <> NIL THEN 
BEGIN 

myNewItem := GetResource('DITL', kSpanishDITL); 

IF myNewItem <> NIL THEN 

BEGIN 

AppendDITL(theDialog, myNewItem, kAppendItem); {kAppendItem = -3} 








ReleaseResource (myNewItem) ; 





docWindow := FrontWindow; {get the front window} 
{if there's a front window, deactivate it} 
IF docWindow <> NIL THEN 

DoActivate (docWindow, FALSE, event); 





ShowWindow(theDialog); {show dialog box with appended item} 
MyAdjustMenus; {adjust menus as needed} 
REPEAT 
ModalDialog(@MyEventFilter, itemHit); 
{handle clicks in checkboxes here} 
UNTIL ((itemHit = kSpellCheck) OR (itemHit = kCancel)); 
{handle clicks in buttons here} 








DisposeDialog(theDialog) ; 
DoSpellBoxWithSpanish := kSuccess; 
END 
ELSE 
DoSpellBoxWithSpanish := kFailed; 
END 
ELSE DoSpellBoxWithSpanish := kFailed; 
END; 


The DoSpel1BoxWithSpanish routine uses Get NewDialog to create a dialog box. 

As you'll see in Listing 6-14, the dialog resource passed to GetNewDialog has a 
resource ID of 402, and this dialog resource in turn specifies an item list resource with 
resource ID 402. The DoSpel1BoxWithSpanish routine then uses the Resource 
Manager function Get Resource to obtain a handle to a second item list resource; this 
item list resource contains the “Include Spanish Dictionary” checkbox. By setting a value 
of —3 in the last parameter of AppendDITL, the DoSpel1BoxWithSpanish routine 
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appends the items in the second item list resource relative to item number 3 (the “Ignore 
Words in All Caps” checkbox) in the dialog box. Listing 6-14 shows the dialog resource 
for the dialog box, its regular item list resource, and the item list resource that 
AppendDITL adds to it. 


Listing 6-14 Rez input for a dialog box and the item appended to it 


# define kSpellCheckID 402 /*resource ID for Spell Check dialog box*/ 
# define kSpellCheckDITL 402 /*resource ID for item list resource*/ 
# define kSpanishDITL 257 /*resource ID for item list resource to append*/ 


# define kAppendHelp 257 /*resource ID for 'hdlg' for appended item*/ 





resource 'DLOG' (kSpellCheckID, purgeable) {/*Spell Check dialog box*/ 


hi 


{62, 184, 216, 448}, 

dBoxProc, /*make it modal*/ 

invisible, /*make it initially invisible*/ 
noGoAway, 0x0, kSpellCheckDITL, "Spellcheck Options", 
alertPositionParentWindow /*place over the document window*/ 


resource 'DITL' (kSpellCheckDITL, purgeable) { 


hi 


/*items for Spell Check dialog box*/ 

/*ITEM NO. 1, the "Spell Check" button, goes here*/ 

/*ITEM NO. 2, the "Cancel" button, goes here*/ 

/*ITEM NO. 3*/ 

{48, 23, 67, 202}, CheckBox {enabled, "Ignore Words in All Caps"}, 

/*ITEM NO. 4*/ 

{83, 23, 101, 196}, CheckBox {enabled, "Ignore Slang Terms"}, 
/*static text, help item, etc. go here*/ 





/*add this item list resource to Spell Check dialog box only when */ 
/* Spanish language dictionary is installed*/ 


resource 'DITL' (kSpanishDITL, purgeable) { 


hi 


{ {18, 0, 36, 209},CheckBox {enabled, "Include Spanish Dictionary"}, 
{0,0,0,0}, HelpItem {disabled, HMScanAppendhdlg{kAppendHelp}} /*help*/ 


The dialog resource specifies that the dialog box is invisible so that the application 
can add the new item to the dialog box before displaying it. In Listing 6-13, the 
DoSpel1lBoxWithSpanish routine uses the Window Manager procedure 
ShowWindow to display the dialog box after its new item has been appended. 
(“Displaying Alert and Dialog Boxes” beginning on page 6-61 describes more fully 
how to display dialog boxes.) 
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The appended item list resource includes a help item that causes the Help Manager to 
use the help resource associated with that item list resource in addition to the help 
resource originally associated with the dialog box. See the chapter “Help Manager” in 
Inside Macintosh: More Macintosh Toolbox for information about using the 
HMScanAppendhd1g identifier in a help item. 


Listing 6-13 uses the Resource Manager procedure ReleaseResource. The 
AppendDITL procedure modifies the contents of the dialog box (for instance, by 
enlarging it). To use an unmodified version of the dialog box at a later time, your 
application needs to use ReleaseResource to release the memory occupied by the 
appended item list. Otherwise, if your application calls AppendDITL to add items to 
that dialog box again, the dialog box will remain modified by your previous call—for 
example, it will still be longer at the bottom if you previously used the 
appendDITLBottom constant. 





When you can call the ShortenDITL procedure to remove items from the end of a 
dialog item list, you specify a pointer to the dialog box and the number of items to 
remove from the end of the item list. Note that Short enDITL does not automatically 
resize the dialog box; you can use the Window Manager procedure SizeWindow if you 
need to resize the dialog box. You can use the CountDITL function to determine the 
number of items in the item list resource for a dialog box. 


Using an Application-Defined Item to Draw the Bold Outline 
for a Default Button 


You can define your own type of item for dialog boxes. You might wish, for example, 
to display a clock with the current time in a dialog box. You can also use application- 
defined items to draw a bold outline around the default button in a dialog box. 


You should not use application-defined items in an alert box because they add 
unnecessary programming complications. If you need an application-defined item, 
use a dialog box instead. 


To define your own item, include an item of type UserItem in your item list resource; 

it should have a display rectangle, but no text and no resource ID associated with 

it. The dialog resource that uses this item list resource must specify the invisible 
constant. This makes the dialog box invisible while you install a draw procedure for 
your application-defined item. After installing the procedure that draws the application- 
defined item, you display the dialog box by using the Window Manager procedure 
ShowWindow. 


For example, Figure 6-32 on page 6-53 illustrates a dialog box that outlines the default 
button (Spell Check). To outline the button, the application must add an item of type 
UserItem to the item list resource for that dialog box. 


So that an application-defined drawing procedure can draw a border around the Spell 
Check button, the item list resource in Listing 6-15 specifies a larger display rectangle for 
the application-defined item than for the Spell Check button. 
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Listing 6-15 Rez input for an application-defined item in an item list 


"DITL' (kSpellCheckDITL, purgeable) { 
/*ITEM NO. 1: OK button--the default*/ 





170, 144, 254}, Button {enabled,"Spell Check"}, 


/*ITEMs 2-5 go here: Cancel button, two checkboxes, and static text*/ 
/*ITEM NO. 6: application-defined item*/ 


164, 152, 260}, /*6th item*/ 


UserItem { /*draw procedure for item draws an outline*/ 


disabled, /*1st item lies inside this--lst is enabled*/ 


The application-defined item is disabled because the Spell Check button, which lies 
within the application-defined item, is enabled. Because the Spell Check button is listed 
before the application-defined item in this item list resource, the Dialog Manager reports 
when the user clicks the Spell Check button. However, note that when application- 
defined items are enabled, the Dialog Manager reports their item numbers when the 
user clicks them. 


Note 

Although the draw procedure for an application-defined item can draw 
outside the item’s display rectangle, this is not recommended because 
if the Dialog Manager receives an update event involving an area 
outside the display rectangle but inside the area where you draw 

your application-defined item, the Dialog Manager won’t call your 
draw procedure. @ 


Listing 6-14 on page 6-55 shows the dialog resource for the dialog box. Notice that the 
invisible constant in the dialog resource specifies that the dialog box should initially 
be invisible. 


You must provide a procedure that draws your application-defined item. Your draw 
procedure must have two parameters: a dialog pointer and an item number from the 
dialog box’s item list resource. For example, this is how you should declare the draw 
procedure if you were to name it MyDrawDefaultButtonOutline: 


PROCEDURE MyDrawDefaultButtonOutline (theDialog: DialogPtr; 
theItem: Integer); 


The parameter theDialog is a pointer to the dialog box containing the application- 
defined item. (If your procedure draws in more than one dialog box, this parameter tells 
your procedure which dialog box to draw in.) The parameter theItem is anumber 
corresponding to the position of an item in the item list resource for the dialog box. (In 
case the procedure draws more than one item, this parameter tells the procedure which 
one to draw.) 
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To install this draw procedure, use the GetDialogItem and SetDialogItem 
procedures. Use Get DialogItem to return a handle to the application-defined item 
specified in the item list resource. Then use SetDialogItem to replace this handle 
with a pointer to your draw procedure. When calling your draw procedure, the Dialog 
Manager sets the current port to the dialog box’s graphics port. The Dialog Manager 
then calls your procedure to draw the application-defined item as necessary—for 
instance, when you display the dialog box and whenever the Dialog Manager receives 
an update event for the dialog box. 


Listing 6-16 illustrates how to install the procedure that draws a bold outline. In this 
listing, GetDialogItem gets a handle to the application-defined item (which is 
the sixth item in the item list resource from Listing 6-15). The procedure pointer 
@MyDrawDefaultButtonOutline, which is coerced to a handle, is then passed 
to SetDialogItem, which sets the draw procedure into the dialog record. 





Listing 6-16 Installing the draw procedure for an application-defined item 


FUNCTION DisplayMyDialog (VAR theDialog: DialogPtr): OSErr; 





VAR 
itemType: Integer; 
itemHandle: Handle; 
itemRect: Rect; 
docWindow: WindowPtr; 
event: EventRecord; 
BEGIN 
{begin by creating an invisible dialog box} 
theDialog := GetNewDialog(kSpellCheckID, NIL, Pointer(-1)); 
IF theDialog <> NIL THEN 








BEGIN 





{get a handle to the application-defined item (i.e., userItem) } 





GetDialogItem(theDialog, kUserItem, itemType, itemHandle, itemRect); 
{install the drawing procedure for the application-defined item} 
SetDialogItem(theDialog, kUserItem, itemType, 
Handle (@MyDrawDefaultButtonOutline), itemRect) ; 

docWindow := FrontWindow; {get the front window} 

{if there's a front window, deactivate it} 
IF docWindow <> NIL THEN 

DoActivate (docWindow, FALSE, event); 


ShowWindow (theDialog) ; {display the dialog box} 
MyAdjustMenus; {adjust menus as needed} 
DisplayMyDialog := kSuccess; 
END 
ELSE DisplayMyDialog := kFailed; 
{call ModalDialog and handle events in dialog box here} 
END; 
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Use the Window Manager procedure ShowWindow to display the previously invisible 
dialog box. When ShowWindow is called in this example, a bold outline is drawn inside 
the application-defined item and around the Spell Check button. 


Listing 6-17 shows a procedure that draws a bold outline around a button of any size 
and shape. This procedure can be used to draw the outline around the Spell Check 
button from the previous example. 


Listing 6-17 Creating a draw procedure that draws a bold outline around the default button 








CEDURE MyDrawDefaultButtonOutline(theDialog: DialogPtr; theItem: Integer); 
ST 

kButtonFrameInset = -4; 

kButtonFrameSize = 3; 

kCntrActivate = 0; 

itemType: Integer; {returned item type} 
itemRect: Rect; {returned display rectangle} 
itemHandle: Handle; {returned item handle} 
curPen: PenState; 

buttonOval: Integer; 

fgSaveColor: RGBColor; 

bgColor: RGBColor; 

newfgColor: RGBColor; 

newGray: Boolean; 

oldPort: WindowPtr; 

isColor: Boolean; 


targetDevice: GDHandle; 

IN 

{get the default button & draw a bold border around it} 
GetDialogItem(theDialog, kDefaultButton, itemType, itemHandle, itemRect); 
GetPort (oldPort); 

SetPort (ControlHandle(itemHandle) **.contrlOwner) ; 

GetPenState (curPen) ; 

PenNormal; 








InsetRect (itemRect, kButtonFrameInset, kButtonFramelInset) ; 

FrameRoundRect (itemRect, 16, 16); 

buttonOval := (itemRect.bottom - itemRect.top) DIV 2 + 2; 

IF ((CGrafPtr (ControlHandle (itemHandle) **.contrlOwner)*.portVersion) = 
kIsColorPort) THEN 





isColor := TRUE 
ELSE 
isColor := FALSE; 


IF (ControlHandle(itemHandle)**.contrlHilite <> kCntrlActivate) THEN 
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BEGIN {control is dimmed, so draw gray default button outline} 





newGray := FALSE; 
IF isColor THEN 
BEGIN 
GetBackColor (bgColor) ; 
GetForeColor (fgSaveColor) ; 
newfgColor := fgSaveColor; 
{get the device on which this dialog box is displayed} 





targetDevice := 
MyGetDeviceFromRect (ControlHandle (itemHandle) **.contrlRect) ; 
{use the gray defined by the display device} 





newGray := GetGray(targetDevice, bgColor, newfgColor); 
END; 
IF newGray THEN 

RGBForeColor (newfgColor) 
ELSE 

PenPat (gray); 





PenSize(kButtonFrameSize, kButtonFrameSize) ; 
FrameRoundRect (itemRect, buttonOval, buttonOval); 
IF isColor THEN 
RGBForeColor (fgSaveColor) ; 
END 
ELSE {control is active, so draw default button outline in black} 
BEGIN 
PenPat (black) ; 
PenSize(kButtonFrameSize, kButtonFrameSize) ; 
FrameRoundRect (itemRect, buttonOval, buttonOval); 
END; 
SetPenState(curPen) ; 
SetPort (oldPort) ; 





, 


Listing 6-17 uses Get DialogItem to get the Spell Check button and then uses 
several QuickDraw routines to draw a black outline around that button’s display 
rectangle when the button is active. If the button is inactive (that is, dimmed), 
MyDrawDefaultButtonOutline drawsa gray outline. 


Before drawing a gray outline, MyDrawDefaultButtonOutline determines whether 
the dialog box uses a color graphics port. As explained in “Including Color in Your Alert 
and Dialog Boxes” beginning on page 6-75, you can supply a dialog box with a color 
graphics port by creating a dialog color table ('dctb"') resource with the same resource 
ID as the dialog resource. If the dialog box uses a color graphics port, 
MyDrawDefaultButtonOut line uses the Color QuickDraw function Get Gray to 
return a blended gray based on the foreground and background colors. Then 
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MyDrawDefaultButtonOutline uses this gray for outlining the dimmed default 
button. Otherwise, MyDrawDefaultButtonOut line uses the QuickDraw procedure 
PenPat to draw a gray outline on black-and-white monitors. 


Displaying Alert and Dialog Boxes 


You typically define alerts and dialog boxes in resources, as described in “Creating Alert 
Sounds and Alert Boxes” beginning on page 6-18 and in “Creating Dialog Boxes” 
beginning on page 6-23. To create an alert or a dialog box, you use a Dialog Manager 
function—such as Alert or GetNewDialog—that incorporates information from your 
item list resource and from your alert resource or dialog resource into a data structure, 
called a dialog record, in memory. The Dialog Manager creates a dialog record, which is a 
data structure of type DialogRecord, whenever your application creates an alert or a 
dialog box. 


The Dialog Manager automatically displays alert boxes at the appropriate alert stages; it 
also automatically displays those dialog boxes that you specify as visible in their dialog 
resources. But you must use a Window Manager routine such as ShowWindow to display 
dialog boxes that you specify as invisible in their dialog resources. 


When you use a function that creates an alert (namely, Alert, StopAlert,NoteAlert, 
orCautionAlert), the Dialog Manager automatically displays the alert box at the alert 
stages that you specify with the visible constant in your alert resource. You do not use 
any routines other than the Alert, StopAlert, NoteAlert, and CautionAlert 
functions to display an alert box. 


When you specify the visible constant in a dialog resource, the Dialog Manager 
immediately displays the dialog box when you use the GetNewDialog function. If 
you instead specify the invisible constant so that the dialog box is initially invisible 
when you call GetNewDialog, use the Window Manager procedure ShowWindow 

to display it. This is useful if you need to manipulate a dialog item dynamically using 
GetDialogItemand SetDialogItem before you display the dialog box. For example, 
if you want to install an application-defined draw procedure for a dialog box, you 
specify the invisible constant in a dialog resource, pass the resource ID of that dialog 
resource in a parameter to Get NewDialog, use GetDialogItemand SetDialogItem 
to install the application-defined draw procedure, then call ShowWindow to display the 
dialog box, as previously shown in Listing 6-16 on page 6-58. 

You should always specify Pointer (-1) asa parameter to GetNewDialog to display a 
dialog box as the active (that is, frontmost) window. 


You should perform the following tasks in conjunction with displaying an alert box or a 
dialog box: 
m Specify an appropriate screen position at which to display the alert box or dialog box. 


m Deactivate the frontmost window (if one exists) before displaying an alert box or a 
modal dialog box. 


m Determine whether you've already created a modeless dialog box and, if so, select it 
instead of creating a new instance of it. 


a Adjust your menus appropriately for a modal dialog box with editable text items and 
for any movable modal and modeless dialog box you wish to display. 
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The DialogSelect function uses the QuickDraw procedure Set Port to make the alert 
or dialog box the current graphics port. The ModalDialog procedure and the functions 
that create alert boxes use DialogSelect to respond to update and activate events. You 
can also use DialogSelect to respond to update and activate events in your modeless 
and movable modal dialog boxes. In response to update events, you can instead use the 
UpdateDialog function, which also makes the dialog box the current graphics port. 

In these cases, it’s generally not necessary for your application to call SetPort when 
displaying, updating, or activating alert boxes and dialog boxes. See Inside Macintosh: 
Imaging for more information about SetPort. 


These and other related issues are explained in detail in the next several sections of 
this chapter. 


Positioning Alert and Dialog Boxes 


As previously described in “Creating Alert Sounds and Alert Boxes” beginning on 

page 6-18 and “Creating Dialog Boxes” beginning on page 6-23, you specify a rectangle 
in every alert resource and dialog resource. The dimensions of this rectangle determine 
the dimensions of the alert box or dialog box. You can also let the rectangle coordinates 
serve as the global coordinates that determine the position of the alert box or dialog box, 
or you can let the Dialog Manager automatically locate it for you according to three 
standard positions. To specify these standard positions in System 7, your application can 
use the following constants in the Rez input files for alert resources and dialog resources: 


Constant Description 

alertPositionParentWindow Position the alert or dialog box over 
the frontmost window 

alertPositionMainScreen Position the alert or dialog box on 
the main screen 

alertPositionParentWindowScreen Position the alert or dialog box on 
the screen containing the frontmost 
window 


If your application positions alert or dialog boxes on its own, don’t use these 
constants, because your code may conflict with the Dialog Manager. If you do use 
these constants, use them to specify the positions of both alert boxes and dialog boxes. 


The next three figures illustrate various alert boxes that might appear when the user is 
working on two monitors: a 12-inch monitor (the main screen) that displays the menu 
bar and a full-page monitor that displays a document window. These figures show 
where the Dialog Manager places an alert box according to the position specified in 
the alert resource. 


Figure 6-33 shows an alert box displayed in response to an error made by the 
user while working on a document; the alert resource specifies the 
alertPositionParentWindow constant, which tells the Dialog Manager to 
position the alert box over the frontmost window so that the window’s title bar 
appears. This position is appropriate for an alert box or a dialog box that relates 
directly to the frontmost window. You should always try to position alert boxes 
and dialog boxes where the user is working. 
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Figure 6-33 An alert box in front of a document window 





Not all alert boxes or dialog boxes relate to the frontmost window. Some may relate 

only to actions the user performs on the main screen. For example, Figure 6-34 

illustrates an alert box displayed when the user chooses the About command from 

the Apple menu. For an alert box or dialog box such as this, you should specify the 
alertPositionMainScreen constant in the alert or dialog resource. Figure 6-34 
shows how the Dialog Manager centers such an alert box near the top of the main screen. 


Figure 6-34 An alert box on the main screen 
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Sometimes you may need to display an alert box or a dialog box that applies neither to 
the frontmost window nor to an action performed on the main screen. To catch the user’s 
attention, you should position such an alert or dialog box on the screen where the user is 
working. For example, if you need to alert the user that available disk space is low, you 
should specify the alertPositionParentWindowScreen constant. Figure 6-35 
shows how the Dialog Manager displays such an alert box or dialog box when a 
document window appears on a screen other than the main screen. 


Figure 6-35 An alert box in the alert position of the document window screen 





If you don’t specify a positioning constant, the Dialog Manager uses the rectangle 
coordinates in your alert resource or dialog resource as global coordinates specifying 
where to position your alert or dialog box. If you wish to specify the position yourself in 
this manner, you should generally try to center alert and dialog boxes between the left 
and right margins of the screen or the window where the user is working, whichever is 
most appropriate. If you don’t use the positioning constants, you should also place the 
tops of alert and dialog boxes (including the title bars of modeless and movable modal 
dialog boxes) below the menu bar. You can use the GetMBarHeight function, described 
in the chapter “Menu Manager” in this book, to determine the height of the menu bar. 





Deactivating Windows Behind Alert and Modal Dialog Boxes 


For alert and modal dialog boxes, the ModalDialog procedure traps all events before 
they are passed to your event loop, which normally handles activate events for your 
windows. Thus, if a window is active, you must explicitly deactivate it before displaying 
an alert box or a modal dialog box. 


Your modeless dialog boxes and movable modal dialog boxes never use the 
ModalDialog procedure. Therefore, you do not have to deactivate the frontmost 
window explicitly before displaying a modeless or a movable modal dialog box. 
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Instead, the Event Manager continues sending your application activate events for 
your windows as needed, which you typically handle in your normal event loop. (The 
chapters “Event Manager” and “Window Manager” in this book explain how to 
activate and deactivate windows.) 


Plate 2 at the front of this book shows an alert box that an application displays when the 
user chooses the About command in the Apple menu. Listing 6-18 shows an application- 
defined routine, ShowMyAbout Box, that displays this alert box. 


Listing 6-18 Deactivating the front window before displaying an alert box 


PROCEDURE ShowMyAboutBox; 





VAR 
itemHit: Integer; 
docWindow: WindowPtr; 
event: EventRecord; 
BEGIN 
docWindow := FrontWindow; {get the front window} 


{if there's a front window, deactivate it} 
IF docWindow <> NIL THEN 
DoActivate (docWindow, FALSE, event); 
{then show the alert box} 
itemHit := Alert (kAboutBoxID, @MyEventFilter) ; 
END; 


The ShowMyAbout Box routine uses the Window Manager function Front Window. If 
FrontWindow returns a valid pointer, ShowMyAbout Box calls its DoActivate 
procedure to deactivate that window before calling the Alert function to display the 
alert box. When the user clicks the OK button, the alert box is dismissed. The Event 
Manager then sends the application update events so that it can update the contents of 
any windows as appropriate, and the Event Manager sends the application an activate 
event so that it can activate the previously frontmost window again. The application 
handles these events in its normal event loop. 


If your application does not display an alert box during certain alert stages, use the 
GetAlert Stage function to test for those stages before deactivating the active window. 
The GetAlertStage function returns the last occurrence of an alert as a number from 

0 to 3. Figure 6-36 shows an alert box that appears only after the user repeats an error 
three consecutive times. 


Figure 6-36 An alert box displayed only after the third alert stage 





i) You must keep your graphic within 


the margins of the page. 
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Listing 6-19 shows how you might use GetAlert Stage to determine if such an alert 
needs to be displayed before deactivating the document window. 


Listing 6-19 Using Get Alert Stage to determine when to deactivate the front window 


PROCEDURE MyAlert; 


VAR 


BEG 


END; 


itemHit: Integer; 

alertStage: Integer; 

docWindow: WindowPtr; 

event: EventRecord; 

IN 

docWindow := FrontWindow; 

alertStage := GetAlertStage; 

IF (alertStage >= 2) AND (docWindow <> NIL) THEN {at 3rd alert stage, } 
DoActivate (docWindow, FALSE, event); { deactivate front window & } 

itemHit := StopAlert (kStopAlertID, @MyEventFilter) ; { display alert box} 


, 


Displaying Modeless Dialog Boxes 


For a modeless dialog box, check to make sure it isn’t already open before you create and 
display it. For example, the modeless dialog box shown in Figure 6-37 should appear 
when the user chooses the Global Changes command. After invoking this command, the 
user may select another window, thereby deactivating the modeless dialog box. 


Figure 6-37 A modeless dialog box for changing text in a document 





=> Global Changes 








So as not to create multiple versions of this dialog box whenever the user chooses the 
Global Changes command, the application-defined routine DoGlobalChangesDialog, 
shown in Listing 6-20, checks whether the dialog box already exists. 
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Listing 6-20 Ensuring that the modeless dialog box isn’t already open before creating it 


FUNCTION DoGlobalChangesDialog: OSErr; 














BEGIN 
DoGlobalChangesDialog := kSuccess; {assume success} 
IF gChangeDialogPtr = NIL THEN {it doesn't exist, so create it} 
BEGIN 
gChangeDialogPtr := GetNewDialog(kGlobalChangesDlog, NIL, Pointer(-1)); 
IF gChangeDialogPtr = NIL THEN {handle failure} 
BEGIN 
DoGlobalChangesDialog := kFailed; 
EXIT (DoShowModelessFindDialogBox) ; 
END; 


{set window refCon to store value that identifies the dbox} 
SetWRefCon(gChangeDialogPtr, LongInt (kGlobalChangesDlog) ); 

END 

ELSE {it does exist, so display and select it} 

BEGIN 
ShowWindow(gChangeDialogPtr); {it's hidden; so show it} 
SelectWindow(gChangeDialogPtr);{bring it to the front} 

END; 

MyAdjustMenus; {adjust the menus} 

END; 


In this example, a pointer to the modeless dialog box is stored in a global variable. If 

the global variable does not contain a pointer, DoGlobalChangesDialog uses 
GetNewDialog to create and draw the dialog box. Later, if the user decides to close the 
modeless dialog box, the application merely hides it so that when the user needs it again, 
DoGlobalChangesDialog can display the dialog box in the same location and with 
the same text selected as when the user last used it. Hiding this dialog box is illustrated 
later in Listing 6-30 on page 6-94. 


If the dialog box has already been created, DoGlobalChangesDialog uses the Window 
Manager procedures ShowWindow to make the dialog box visible and SelectWindow 
to make it active. 


Finally, DoGlobalChangesDialog uses the application-defined routine 
MyAdjustMenus to adjust the menus as appropriate for the modeless dialog box. 


Listing 6-34 on page 6-98 illustrates an application-defined routine, 
DoActivateGlobalChangesDialog, that handles activate events for this 
modeless dialog box. The DoActivateGlobalChangesDialog routine in 
turn uses DialogSelect, which sets the graphics port to the modeless dialog 
box whenever the user makes it active. 
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Adjusting Menus for Modal Dialog Boxes 


The Dialog Manager and the Menu Manager interact to provide various degrees of 
access to the menus in your menu bar. For alert boxes and modal dialog boxes without 
editable text items, you can simply allow system software to provide the appropriate 
access to your menu bar. 


When your application displays either an alert box or a modal dialog box (that is, a 
window of type dBoxP roc), these actions occur: 


1. System software disables all menu items in the Help menu, except the Show Balloons 
(or Hide Balloons) command, which system software enables. 


2. System software disables all menu items in the Application menu. 


3. If the Keyboard menu appears in the menu bar, system software enables that menu 
but disables the About Keyboards command. 


When your application displays an alert box or calls the ModalDialog procedure 
for a modal dialog box (described in “Responding to Events in Modal Dialog Boxes” 
beginning on page 6-82), the Dialog Manager determines whether any of the following 
cases is true: 


m Your application does not have an Apple menu. 


m Your application has an Apple menu, but the menu is disabled when the dialog box 
is displayed. 

m Your application has an Apple menu, but the first item in that menu is disabled when 
the dialog box is displayed. 


If none of these cases is true, system software behaves as follows: 
1. The Menu Manager disables all of your application’s menus. 


2. If the modal dialog box contains a visible and active editable text field—and if the 
menu bar contains a menu having commands with the standard keyboard equivalents 
Command-X, Command-C, and Command-V—then the Menu Manager enables 
those three commands and the menu that contains them. The user can then use either 
the menu commands or their keyboard equivalents to cut, copy, and paste text. 

(The menu item having keyboard equivalent Command-X must be one of the first 
five menu items.) 


When your application displays alert boxes and modal dialog boxes with no editable text 
items, it can safely allow system software to handle menu bar access as described in 
steps 1 and 2. 


However, because system software cannot handle the Undo or Clear command (or any 
other context-appropriate command) for you, your application should handle its own 
menu bar access for modal dialog boxes with editable text items by performing the 
following tasks: 


m disable the Apple menu or the first item in the Apple menu (typically, your 
application’s About command) in order to take control of its menu bar access 
when displaying a modal dialog box 
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m disable all of its menus except the Edit menu, as well as any inappropriate commands 
in the Edit menu 


m use the Dialog Manager procedures DialogCut, DialogCopy, DialogPaste, 
and DialogDelete to support the Cut, Copy, Paste, and Clear commands in editable 
text items 


m provide your own code for supporting the Undo command 

m enable your application’s items in the Help menu as appropriate (system software 
disables all items except the Hide Balloons/Show Balloons command) 

You don’t need to do anything else for the system-handled menus—namely, Application, 

Keyboard, and Help. System software handles these menus for you automatically. 


The DialogCut, DialogCopy, DialogPaste, and DialogDelete procedures are 
described beginning on page 6-132. Your application can test whether a dialog box is the 
front window when handling mouse-down events in the Edit menu and then call these 
routines as appropriate. 


Figure 6-38 illustrates how an application disables all of its own menus except its Edit 
menu when displaying a modal dialog box containing editable text items. Access to the 
Edit menu benefits the user who instead of typing prefers copying from and pasting into 
editable text items. 


Figure 6-38 Menu access when displaying a modal dialog box 


@ fe Edit feed Tays 


Mig Window 


Please type your dog’s name: 


Cancel OK 








Listing 6-21 on the next page shows an application-defined routine, MyAdjustMenus, 
that the SurfWriter application calls to adjust its menus after it displays a window or 
dialog box, but before it calls ModalDialog to handle events in a modal dialog box. 
When MyAdjustMenus determines that the frontmost window is a modal dialog box 
containing an editable text item, it calls another application-defined routine, 
MyAdjustMenusForDialogs, which adjusts the menus appropriately. Listing 6-22 on 
the next page shows the MyAdjustMenusForDialogs routine. 
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Listing 6-21 Adjusting menus for various windows 


PROCEDURE MyAdjustMenus; 
VAR 
window: WindowPtr; 
windowType: Integer; 
menu: MenuHandle; 
BEGIN 


window := FrontWindow; 








windowType := MyGetWindowType (window) ; 

CASE windowType OF 

kMyDocWindow: {document window is in front} 
MyAdjustMenusForDocWindows; 

kMyDialogWindow: {a dialog box is in front} 
MyAdjustMenusForDialogs; 

kDAWindow: {adjust menus accordingly for a DA window} 
MyAdjustMenusForDA; 

kNil: {there isn't a front window} 











MyAdjustMenusNoWindows; 
END; {of CASE} 

DrawMenuBar; {redraw menu bar} 
END; 





The MyAdjustMenusForDialogs routine in Listing 6-22 first determines what type of 
dialog box is in front: modal, movable modal, or modeless. For modal dialog boxes, 
MyAdjustMenusForDialogs disables the Apple menu so that the application can take 
control of its menus away from the Dialog Manager. The MyAdjustMenusForDialogs 
routine then uses the Menu Manager routines GetMenuHandle and DisableItem to 
disable all other application menus except the Edit menu. (To provide help balloons that 
explain why these menus are unavailable to the user, MyAdjustMenusForDialogs 
uses the Help Manager procedure HMSetMenuRes ID to reassign help resources to these 
menus; see the chapter “Help Manager” in Inside Macintosh: More Macintosh Toolbox for 
more information.) 


Listing 6-22 Disabling menus for a modal dialog box with editable text items 


PROCEDURE MyAdjustMenusForDialogs; 
VAR 


window: WindowPtr; 





windowType: Integer; 








myErr: OSErr; 
menu: MenuHandle; 
BEGIN 
window := FrontWindow; 
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windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyModalDialogs: 
BEGIN 
menu := GetMenuHandle (mApple) ; {get handle to Apple menu} 
IF menu = NIL THEN 
EXIT (MyAdjustMenusForDialogs) ; 





DisableItem(menu, 0); {disable Apple menu to get control of menus} 
myErr := HMSetMenuResID(mFile, kFileHelpID); {set up help balloons} 
menu := GetMenuHandle(mFile); {get handle to File menu} 


IF menu = NIL THEN 
EXIT (MyAdjustMenusForDialogs) ; 
DisableItem(menu, 0); {disable File menu} 
myErr := HMSetMenuResID(mFile, kFileHelpID); {set up help balloons} 
IF myErr <> NoErr THEN 
EXIT (MyAdjustMenusForDialogs) ; 
menu := GetMenuHandle(mTools); {get handle to Tools menu} 
IF menu = NIL THEN 
EXIT (MyAdjustMenusForDialogs) ; 
DisableItem(menu, 0); {disable Tools menu} 
myErr := HMSetMenuResID(mTools, kToolsHelpID) ; {help balloons} 
IF myErr <> NoErr THEN 
EXIT (MyAdjustMenusForDialogs) ; 
MyAdjustEditMenuForModalDialogs; 
END; {of kMyModalDialogs CASE} 
kMyGlobalChangesModelessDialog: 





























Hi {adjust menus here as needed} 
kMyMovableModalDialog: 
; {adjust menus here as follows: } 
{ disable all menus except Apple, then } 
{ call MyAdjustEditMenuForModalDialogs for editable text items} 
END; {of CASE} 
END; 


To adjust the items in the Edit menu, MyAdjustMenusForDialogs calls another 
application-defined routine, MyAdjustEditMenuForModalDialogs, which is 
shown in Listing 6-23 on the next page. The MyAdjustEditMenuForModalDialogs 
routine uses application-defined code to implement the Undo command; uses the 
Menu Manager procedure EnableItem to enable the Cut, Copy, Paste, and Clear 
commands when appropriate; and disables the commands that support Edition 
Manager capabilities. Remember that your application should use the Dialog Manager 
procedures DialogCut, DialogCopy, DialogPaste, and DialogDelete to support 
the Cut, Copy, Paste, and Clear commands in editable text items. 
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Listing 6-23 Adjusting the Edit menu for a modal dialog box 


PROCEDURE MyAdjustEditMenuForModalDialogs; 
VAR 
window: WindowPtr; 
menu: MenuHandle; 
selection, undo: Boolean; 


offset: LongInt; 
undoText: Str255; 
BEGIN 

window := FrontWindow; 

menu := GetMenuHandle(mEdit); {get a handle to the Edit menu} 

IF menu = NIL THEN {add your own error handling} 
EXIT (MyAdjustEditMenuForModalDialogs) ; 

undo := MyIsLastActionUndoable (undoText) ; 

IF undo THEN {if action can be undone} 

BEGIN 


EnableItem(menu, iUndo)j; 
SetMenulItemText (menu, iUndo, undoText); 
END 
ELSE {if action can't be undone} 
BEGIN 
SetMenulItemText (menu, iUndo, gCantUndo) ; 
DisableItem(menu, iUndo); 
END; 





selection := MySelection (window) ; 

IF selection THEN 

BEGIN {enable editing items if there's a selection} 
EnableItem(menu, iCut); 
EnableItem(menu, iCopy); 

END 

ELSE 

BEGIN {disable editing items if there isn't a selection} 
DisableItem(menu, iCut); 
DisableItem(menu, iCopy); 

END; 

IF MyGetScrap(NIL, 'TEXT', offset) > 0 THEN 
EnableItem(menu, iPaste) {enable if something to paste} 

ELSE 
DisableItem(menu, iPaste);{disable if nothing to paste} 

DisableItem(menu, iSelectAll); 

DisableItem(menu, iCreatePublisher) ; 

DisableItem(menu, iSubscribeTo); 

DisableItem(menu, iPubSubOptions) ; 

END; 

END; 
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See the chapter “Menu Manager” in this book for more information on menus and the 
menu bar. 


When the user dismisses the alert box or modal dialog box, the Menu Manager restores 
all menus to their state prior to the appearance of the alert or modal dialog box—unless 
your application handles its own menu bar access, in which case you must restore the 
menus to their previous states. You can use a routine similar to MyAdjustMenus, shown 
in Listing 6-21 on page 6-70, to adjust the menus appropriately according to the type of 
window that becomes the frontmost window. 


Adjusting Menus for Movable Modal and Modeless Dialog Boxes 


Although it always leaves the Help, Keyboard, and Application menus and their 
commands enabled, system software does nothing else to manage the menu bar when 
you display movable modal and modeless dialog boxes. Instead, your application 
should allow or deny access to the rest of your menus as appropriate to the context. For 
example, if your application displays a modeless dialog box for a search-and-replace 
command, you should allow access to the Edit menu to assist the user with the editable 
text items, and you should allow use of the File menu so that the user can open another 
file to be searched. However, you should disable other menus if their commands cannot 
be used inside the active modeless dialog box. 


When creating a modeless dialog box, your application should perform the following 
tasks: 


m disable only those menus whose commands are invalid in the current context 


m if the modeless dialog box includes editable text items, use the Dialog Manager 
procedures DialogCut, DialogCopy, DialogPaste, and DialogDelete to 
support the Cut, Copy, Paste, and Clear commands in editable text items 


When your application creates a movable modal dialog box, it should perform the 
following tasks: 


m leave the Apple menu enabled so that the user can open other applications with it 


m if your movable modal dialog box contains editable text items, leave the Edit menu 
enabled but use the Dialog Manager procedures DialogCut, DialogCopy, 
DialogPaste, and DialogDelete to support the Cut, Copy, Paste, and 
Clear commands 


m disable all of your other menus 


Listing 6-21 on page 6-70 shows an application-defined routine, MyAdjustMenus, that 
SurfWriter uses to adjust its menus after it displays a window or dialog box. You can use 
a similar routine to adjust your menus as appropriate given the nature of the active 
window, movable modal dialog box, or modeless dialog box. 
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Displaying Multiple Alert and Dialog Boxes 


You should generally present the user with only one modal dialog box or alert box at a 
time. Sometimes, you may need to present a modal dialog box and an alert box on the 
screen at one time. For example, when the user saves a file with the same name as 
another file, the Standard File Package displays an alert box on top of the standard file 
dialog box. The alert box asks the user whether to replace the existing file. 


Avoid closing a modal dialog box and immediately displaying another modal dialog 
box or an alert box in response to a user action. This situation creates a “tunneling modal 
dialog box” effect that might confuse the user. Missing the content of the previous 

modal dialog box and unable to return to it, the user has difficulty predicting what will 
happen next. 


However, the user should never see more than one modal dialog and one alert box on 
the screen simultaneously. You can present multiple simultaneous modeless dialog 
boxes, just as you can present multiple document windows. 


When you remove an alert box or a modal dialog box that overlies the default button 
of a previous alert box, the Dialog Manager doesn’t redraw that button’s bold outline. 
Therefore, you should not use an alert box if you need to display another overlapping 
alert box or dialog box. Instead, you should create a modal dialog box, and you must 
provide it with an application-defined item that draws the bold outline around the 
default button. The ModalDialog procedure then causes the item to be redrawn after 
an update event. 


In System 7, the Window Manager automatically dims the window frame of a dialog box 
when you deactivate it to display an alert box, another modal dialog box, or a window. 
When you deactivate a dialog box, you should use the Control Manager procedure 
HiliteControl to make the controls of a dialog box inactive. You should also draw the 
outline of the default button of a deactivated dialog box in gray instead of black. Listing 
6-16 on page 6-58 shows an application-defined procedure that draws a gray outline 
when the default button is inactive; Listing 6-34 on page 6-98 shows how to use 
HiliteControl to make buttons inactive and active in response to activate events for a 
dialog box. 


Displaying Alert and Dialog Boxes From the Background 


If you ever need to display an alert box or a modal dialog box while your application is 
running in the background or is otherwise invisible to the user, you should use the 
Notification Manager to post a notification to the user. For example, if your application 
performs lengthy background tasks such as printing many documents or transferring 
large amounts of data to other computers, you might wish to inform the user that the 
operation is completed. In these cases, you should post a notification request to notify 
the user when the operation is completed. Then the Notification Manager automatically 
displays an alert box containing whatever message you specify; you do not need to use 
the Dialog Manager to create the alert box yourself. 


Note that the Notification Manager provides a one-way communications path from your 
application to the user. There is no provision for carrying information back from the user 
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to your application while it is in the background (although it is possible for your applica- 
tion to determine if the notification was received). If you need to solicit information from 
the user, use the Notification Manager to ask the user to bring your application to the 
foreground. The user can then respond to your alert box or modal dialog box. See the 
chapter “Notification Manager” in Inside Macintosh: Processes for information about the 
Notification Manager. 


Including Color in Your Alert and Dialog Boxes 


On color monitors, the Dialog Manager automatically adds color to your alert and dialog 
boxes so that they match the colors of the windows, alert boxes, and dialog boxes used 
by system software. These colors provide aesthetic consistency across all monitors, from 
black-and-white displays to 8-bit color displays. On a color monitor, for example, the 
racing stripes in the title bar of a modeless dialog box are gray, the close box and 
window frame are in color, and the buttons and text are black. 


When you create alert and dialog resources, your application’s alert and dialog boxes 
use the system’s default colors. With the following exceptions, creating alert and dialog 
resources is typically all you need to do to provide color for your alert and dialog boxes: 


m When you need to include a color version of an icon in an alert box or a dialog box, 
you must create a resource of type 'cicn' with the same resource ID as the 
black-and-white 'ICON' resource specified in the item list resource. Plate 2 at the 
front of this book shows an alert box that includes a color icon. 


a If you use GetNewDialog or NewDialog to create a dialog box and you need to 
produce a blended gray color for outlining the inactive (that is, dimmed) default 
button, you must create a dialog color table ('dctb') resource with the same 
resource ID as the dialog resource. 


“Using an Application-Defined Item to Draw the Bold Outline for a Default Button” 
beginning on page 6-56 explains how to create a draw routine that outlines the default 
button of a dialog box. If you deactivate a dialog box, you should dim its buttons and 
use gray to draw the outline for the default button. Because GetNewDialog and 
NewDialog supply black-and-white graphics ports for dialog boxes, you can create a 
dialog color table resource for the dialog box to force the Dialog Manager to supply a 
color graphics port. Then you can use a blended gray color for the outline for the default 
button. (NewColorDialog supplies a color graphics port.) 


Even when you create a dialog color table resource for drawing a gray outline, you 
should not change the system’s default colors. Listing 6-24 shows a dialog color table 
resource that leaves the default colors intact but forces the Dialog Manager to supply a 
color graphics port. 


Listing 6-24 Rez input for a dialog color table resource using the system’s default colors 


data 'dctb' (kGlobalChangesDialog, purgeable) { 
$"0000 0000 0000 FFFF" /*use default colors*/ 
}; 
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By using the system’s default colors, you ensure that your application’s interface is 
consistent with that of the Finder and other applications. However, if you feel absolutely 
compelled to break from this consistency, the Dialog Manager offers you the ability to 
specify colors other than the default colors. Be aware, however, that nonstandard colors 
in your alert and dialog boxes may initially confuse your users. 


Also be aware that despite any changes you make, users can alter the colors of alert and 
dialog boxes anyway by changing the settings in the Color control panel. 


Your application can specify its own colors in an alert color table ('actb') resource 
with the same resource ID as the alert resource or in a dialog color table ('dctb') 
resource with the same resource ID as the dialog resource. Both of these resources have 
exactly the same format as a window color table ('wctb") resource, described in the 
chapter “Window Manager” in this book. 


WARNING 

Because the behavior of color alert and dialog boxes, color items, and 
color icons is unreliable on computers using system software versions 
earlier than System 7, do not specify colors for these elements if you 
wish to maintain backward compatibility. a 


You don’t have to call any new routines to change the colors used in alert or dialog 
boxes. When you call the GetNewDialog function, for example, the Dialog Manager 
automatically attempts to load a dialog color table resource with the same resource ID 
as the dialog resource. 


Likewise, you can change the system default colors for controls and the color, style, 
typeface, and size of text used in an alert box or a dialog box by creating an item color 
table ('ictb') resource with the same resource ID as the item list resource. You don’t 
have to call any routines to create color items. When you use the GetNewDialog 
function, the Dialog Manager looks first for an item color table resource with the same 
resource ID as that of the item list resource. 


Note 

If you want to provide an item color table resource for an alert box or 

a dialog box, you must create an alert color table resource or a dialog 
color table resource, even if the item color table resource has no actual 
color information and describes only static text and editable text style 
changes. You cannot use an item color table resource to set the font on 
computers that do not support Color QuickDraw. Also, be aware that 
changing the default system font makes your application more difficult 
to localize. 


Even if you provide your own 'dctb', 'actb',or 'ictb' resources, you do not 
need to test whether your application is running on a computer that supports Color 
QuickDraw in order to use these resources. 
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Handling Events in Alert and Dialog Boxes 


The next two sections explain how the Dialog Manager uses the Control Manager to 
handle events in controls automatically and how it uses TextEdit to handle events in 
editable text items automatically. The information in these two sections, “Responding to 
Events in Controls” and “Responding to Events in Editable Text Items,” applies to all 
alert boxes and all types of dialog boxes: modal, modeless, and movable modal. 


To display and handle events in alert boxes, you can use the Dialog Manager functions 
Alert, NoteAlert, CautionAlert,and StopAlert. The Dialog Manager handles all 
of the events generated by the user until the user clicks a button (typically the OK or 
Cancel button). When the user clicks a button, the alert box functions invert the button 
that was clicked, close the alert box, and report the user’s selection to your application. 
Your application is responsible for performing the appropriate action associated with 
that button. This is described in detail in “Responding to Events in Alert Boxes” 
beginning on page 6-81. 


For modal dialog boxes, you use the ModalDialog procedure. The Dialog Manager 
handles most of the user interaction until the user selects an item. The ModalDialog 
procedure then reports that the user selected an enabled item, and your application is 
responsible for performing the action associated with that item. Your application 
typically calls ModalDialog repeatedly, responding to clicks on enabled items as 
reported by ModalDialog, until the user clicks OK or Cancel. This is described in detail 
in “Responding to Events in Modal Dialog Boxes” beginning on page 6-82. 


For alert boxes and modal dialog boxes, you should also supply an event filter function 
as one of the parameters to the alert box functions or the ModalDialog procedure. As 
the user interacts with the alert or modal dialog box, these routines pass events to your 
event filter function before handling each event. Your event filter function can handle 
any events not handled by the Dialog Manager or, if necessary, can choose to handle 
events normally handled by the Dialog Manager. This is described in detail in “Writing 
an Event Filter Function for Alert and Modal Dialog Boxes” beginning on page 6-86. 


To handle events in modeless or movable modal dialog boxes, you can use the 
IsDialogEvent function to determine whether the event occurred while a dialog box 
was the frontmost window. For every type of event that occurs when the dialog box is 
active (including null events), IsDialogEvent returns TRUE; otherwise, it returns 
FALSE. When IsDialogEvent returns TRUE, you can use the DialogSelect function 
to handle key-down events in editable text items automatically, to handle update and 
activate events automatically, and to report the enabled items that the user clicks. You 
then respond appropriately to clicks in your active items. 











Alternatively, you can handle events in modeless and movable modal dialog boxes much 
as you handle events in other windows. That is, when you receive an event you can first 
determine the type of event that occurred and then take the appropriate action according 
to which window is in front. If a modeless or movable modal dialog box is in front, you 
can provide code that takes any actions specific to that dialog box and call the 
DialogSelect function to handle any events that your code doesn’t handle. The 
sections “Responding to Mouse Events in Modeless and Movable Modal Dialog Boxes” 
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beginning on page 6-89, “Responding to Keyboard Events in Modeless and Movable 
Modal Dialog Boxes” beginning on page 6-94, and “Responding to Activate and Update 
Events in Modeless and Movable Modal Dialog Boxes” beginning on page 6-97 all take 
this alternate approach. 


Responding to Events in Controls 


The Dialog Manager greatly simplifies the work necessary for you to implement buttons, 
checkboxes, pop-up menus, and radio buttons. For alert boxes and all types of dialog 
boxes—modal, modeless, and movable modal—the Dialog Manager uses Control 
Manager routines to display controls automatically, highlight controls appropriately, and 
report to your application when mouse-down events occur within controls. For example, 
when the user moves the cursor to an enabled button and holds down the mouse button, 
the Dialog Manager uses the Control Manager function TrackCont rol to invert the 
button. When the user releases the mouse button with the enabled button still inverted, 
the Dialog Manager uses TrackControl to report which item was clicked. Your 
application then responds appropriately—for example, by performing the operation 
associated with the OK button, by deselecting any other radio button when a radio 
button is clicked, or by canceling the current operation when the Cancel button is clicked. 


For clicks in checkboxes, pop-up menus, and radio buttons, your application usually 
uses the Control Manager routines Get Cont rolValue and SetControlValue 

to get and appropriately set the items’ values. The chapter “Control Manager” in this 
book explains these routines in detail, but this chapter also offers examples of how 

to use these routines in your alert and dialog boxes. Because the Control Manager does 
not know how radio buttons are grouped, it doesn’t automatically turn one off when 
the user clicks another one. Instead, it’s up to your application to handle this by using 
the GetControlValue and SetCont rolValue routines. 


When the user clicks the OK button, your application performs whatever action is 
necessary according to the values returned by Get Cont rolValue for each of the 
various checkboxes and radio buttons displayed in your alert or dialog box. 


When ModalDialog andDialogSelect call TrackControl, they do not allow you 
to specify any special action procedures necessary for anything more complex than a 
button, radio button, or checkbox. If you need a more complex control that, for example, 
measures how long the user holds down the mouse button or how far the user has 
moved an indicator, you can create your own control (or picture or application-defined 
item that draws a control-like object) in your dialog box. If you use the ModalDialog 
procedure, you must then provide an event filter function that appropriately handles 
events within that item, and if you use the DialogSelect function, you must test for 
and respond to those events yourself. Alternatively, you can use Window Manager 
routines to display an appropriate window and then use the Control Manager to create 
and manage such complex controls yourself. See the chapters “Window Manager” and 
“Control Manager” in this book for more information. 
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Responding to Events in Editable Text Items 


When the user enters or edits text in an editable text item in your dialog boxes, the 
Dialog Manager calls TextEdit to handle the events automatically. (You generally 
shouldn’t include editable text items in alert boxes.) You typically disable editable text 
items because you generally don’t need to be informed every time the user types a 
character or clicks one of them. Instead you need to determine the text only when the OK 
button is clicked. As illustrated in Listing 6-12 on page 6-49, use GetDialogItemText 
to determine the final value of the editable text item after the user clicks the OK button. 


When you use the ModalDialog procedure to handle events in modal dialog boxes and 
when you use the DialogSelect function for modeless or movable modal dialog 
boxes, the Dialog Manager calls TextEdit to handle keystrokes and mouse actions within 
editable text items, so that 


m when the user clicks the item, a blinking vertical bar appears that indicates an 
insertion point where text may be entered 


m when the user drags over text in the item, the text is highlighted; when the user 
double-clicks a word, the word is highlighted; the highlighted selection is then 
replaced by what the user types 


m when the user holds down the Shift key while clicking or dragging, the highlighted 
selection is extended or shortened appropriately 


m when the user presses the Backspace key, the highlighted selection or the character 
preceding the insertion point is deleted 


m when the user presses the Tab key, the cursor automatically advances to the next 
editable text item in the item list resource, wrapping around to the first if there are no 
more items 


If your modeless or movable modal dialog box contains any editable text items, call 
DialogSelect even when WaitNextEvent returns FALSE. This is necessary because 
the DialogSelect function calls the TEIdle procedure to make the text cursor blink 
within your editable text items during null events; otherwise, the text cursor will not 
blink. Listing 6-25 illustrates an application-defined routine, DoIdle, that calls 
DialogSelect whenever the application receives null events while its modeless 
dialog box is the frontmost window. 











Listing 6-25 Using DialogSelect during null events 


PROCEDURE DolIdle (event: EventRecord) ; 
VAR 


window: WindowPtr; 





windowType: Integer; 





itemHit: Integer; 

result: Boolean; 
BEGIN 

window := FrontWindow; 


{determine which type of window--document, } 
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{ modeless dialog box, etc.--is in front} 

windowType := MyGetWindowType (window) ; 

CASE windowType OF 

kMyDocWindow: {document window is frontmost} 
H {see examples in "Event Manager" chapter} 

kMyGlobalChangesModelessDialog: {modeless dialog is frontmost} 
result := DialogSelect (event, window, itemHit); 

END; {of CASE} 

END; 








Generally, your application should handle menu bar access when you display dialog 
boxes containing editable text items. Leave your Edit menu enabled, and use the 
DialogCut, DialogCopy, DialogPaste, and DialogDelete procedures to support 
the Cut, Copy, Paste, and Clear commands and their keyboard equivalents. You should 
also provide your own code to support the Undo command. “Adjusting Menus for 
Modal Dialog Boxes” beginning on page 6-68 and “Adjusting Menus for Movable Modal 
and Modeless Dialog Boxes” on page 6-73 describe how to allow users to access your 
Edit menu when you display dialog boxes. 


If you don’t supply your own event filter function and the user presses the Return or 
Enter key while a modal dialog box is onscreen, the Dialog Manager treats the event as a 
click on the default button (that is, the first item in the list) regardless of whether the 
dialog box contains an editable text item. If your event filter function responds to the 
user pressing Return and Enter by moving the cursor in editable text items, don’t display 
a bold outline around any buttons. If your event filter function responds to the user 
pressing Return and Enter as if the user clicks the default button, then you should 
display a bold outline around the default button. See “Writing an Event Filter Function 
for Alert and Modal Dialog Boxes” beginning on page 6-86 for an example of how to 
map the Return and Enter keys to the default button in your dialog boxes. 


Initially, an editable text item may contain default text or no text. You can provide 
default text either by specifying a text string as the last element for that item in the item 
list resource or by using the SetDialogItemText procedure, which is described on 
page 6-131. 


When a dialog box that contains editable text items is first displayed, the insertion 

point usually appears in the first editable text item in the item list resource. You may 
instead want to use the SelectDialogItemText procedure so that the dialog box 
appears with text selected, or so that an insertion point or a text selection reappears if 
the user makes an error while entering text. For example, the user who accidentally 
types nonnumeric input when a number is required can be given the opportunity to type 
the entry again. The SelectDialogItemText procedure is described in detail on 
page 6-131. 


By default, the Dialog Manager displays editable text items in the system font. To 
maintain visual consistency across applications for your users and to make it easier to 
localize your application, you should not change the font or font size. 
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Responding to Events in Alert Boxes 


After displaying an alert box or playing an alert sound, the Alert, StopAlert, 
CautionAlert, and NoteAlert functions call the ModalDialog procedure to handle 
events automatically for you. 


The ModalDialog procedure, in turn, gets each event by calling the Event Manager 
function GetNext Event. If the event is a mouse-down event outside the content region 
of the alert box, ModalDialog emits the system alert sound and gets the next event. 





The Alert, StopAlert, CautionAlert, and NoteAlert functions continue calling 
ModalDialog until the user selects an enabled control (typically a button). At this time 
these functions remove the alert box from the screen and return the item number of the 
selected control. Your application then responds as appropriate for a click on this item. 


For example, the code that supports the alert box displayed in Figure 6-39 must respond 
to three different events—one for each button that the user may click. 


Figure 6-39 Three buttons for which CautionAlert reports events 





{) Save changes to the SurfWriter document 


“My Window” before closing? 





Listing 6-9 on page 6-47 shows an application-defined routine, named 
MyCloseDocument, for the Close command. If the document has been modified 

since the last save, MyCloseDocument displays the alert box illustrated in Figure 6-39 
before closing the window. After MyCloseDocument displays the caution alert, it 
tests for the item number that CautionAlert returns after it removes the alert box. 

If the user clicks the Save button, CautionAlert returns its item number, and 
MyCloseDocument calls other application-defined routines to save the file, close the 
file, and close the window. If the user clicks the Don’t Save button, MyCloseDocument 
closes the window without saving the file. The only other possible response is for the 
user to click the Cancel button, in which case MyCloseDocument does nothing—the 
Dialog Manager removes the alert box, and MyCloseDocument simply leaves the 
document window as it is. 


The standard event filter function allows users to press the Return or Enter key in lieu of 
clicking the default button. When one of these keys is pressed, the standard event filter 
function returns TRUE to ModalDialog, which in turn causes Alert, StopAlert, 
CautionAlert, and NoteAlert to return the item number of the default button. When 
you write your own event filter function, it should emulate the standard filter function 
by responding in this way to keyboard events involving the Return and Enter keys. 
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For events inside the alert box, ModalDialog passes the event to an event filter function 
before handling the event. The event filter function provides a secondary event-handling 
loop for handling events that ModalDialog doesn’t handle and for overriding events 
that ModalDialog would otherwise handle. You should provide a simple event filter 
function for every alert box and modal dialog box in your application. 


You specify a pointer to your event filter function in the second parameter to the Alert, 
StopAlert, CautionAlert, and NoteAlert functions. In theMyCloseDocument 
routine shown on page 6-47, a pointer to the MyEvent Filter function is specified. In 
most cases, you can use the same event filter function in every one of your alert and 
modal dialog boxes. An example of a simple event filter function that allows background 
applications to receive update events and performs the other necessary event handling is 
provided in “Writing an Event Filter Function for Alert and Modal Dialog Boxes” 
beginning on page 6-86. 





Unless your event filter function handles the event in its own way and returns TRUE, 
ModalDialog handles the event inside the alert box as follows: 


m Inresponse to an activate or update event for the alert box, ModalDialog activates or 
updates its window. 


m Ifthe user presses the mouse button while the cursor is in a control, the Control 
Manager function TrackCont rol tracks the mouse. If the user releases the 
mouse button while the cursor is in an enabled control, Alert, StopAlert, 
CautionAlert, and NoteAlert remove the alert box and return the control’s 
item number. (Generally, buttons should be the only controls you use in alert boxes.) 


m Ifthe user presses the mouse button while the cursor is in any enabled item other than 
acontrol, Alert, StopAlert, CautionAlert, and NoteAlert remove the alert box 
and return the item number. (Generally, button controls should be the only enabled 
items in alert boxes.) 

m Ifthe user presses the mouse button while the cursor is in a disabled item, or if it is 
in no item, or if any other event occurs, Alert, StopAlert, CautionAlert, and 
NoteAlert do nothing. 


Responding to Events in Modal Dialog Boxes 


Call the ModalDialog procedure immediately after displaying a modal dialog box. 
This procedure repeatedly handles events inside the modal dialog box until an event 
involving an enabled item—such as a click in a radio button—occurs. If the event is a 
mouse-down event outside the content region of the dialog box, ModalDialog emits 

the system alert sound and gets the next event. After receiving an event involving an 
enabled item, ModalDialog returns the item number. Normally you then do whatever 
is appropriate in response to an event in that item. Your application should continue 
calling ModalDialog until the user selects the OK or Cancel button, at which point your 
application should close the dialog box. 


For example, if the user clicks a radio button, your application should get the value 
of that button, turn off any other selected radio button within its group, and call 
ModalDialog again to get the next event. If the user clicks the Cancel button, your 
application should restore the user’s work to its state just before the user invoked the 
dialog box, and then your application should remove the dialog box from the screen. 
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Note 
Do not use ModalDialog for modeless or movable modal 
dialog boxes. @ 


The code that supports the modal dialog box shown in Figure 6-40 must respond to 
events in four controls: two checkboxes and two buttons. 


Figure 6-40 Four items for which ModalDialog reports events 





WipeOut typing correction options: 


CJ Ignore Words in All Caps 


CJ Ignore Slang Terms 








Listing 6-26 illustrates an application-defined routine, MySpel1CheckDialog, that 
responds to events in these four controls. 


Listing 6-26 Responding to events in a modal dialog box 


FUNCTION MySpellCheckDialog: OSErr; 


VAR 
docWindow: WindowPtr; 
ignoreCapsCheck: Boolean; 
ignoreSlangCheck: Boolean; 
spellDialog: DialogPtr; 
itemHit, itemType: Integer; 
itemHandle: Handle; 
itemRect: Rect; 
capsVal: Integer; 
slangVal: Integer; 
event: EventRecord; 
BEGIN 
capsVal := 0; 
slangVal := 0; 
ignoreCapsCheck := FALSE; 
ignoreSlangCheck := FALSE; 
MySpellCheckDialog := kSuccess; {assume success} 
docWindow := FrontWindow; {get front window} 


IF docWindow <> NIL THEN 


Using the Dialog Manager 6-83 


CHAPTER 6 


Dialog Manager 


DoActivate (docWindow, FALSE, event); {deactivate document window} 
spellDialog := GetNewDialog(kSpellCheckID, NIL, Pointer(-1)); 
IF spellDialog = NIL THEN 
BEGIN 
MySpellCheckDialog := kFailed; 
Exit (MySpellCheckDialog) ; 
END; 
MyAdjustMenus; {adjust menus as needed} 


GetDialogItem(spellDialog, kUserItem, itemType, itemHandle, itemRect) ; 





SetDialogItem(spellDialog, kUserItem, itemType, 
Handle (@MyDrawDefaultButtonOutline), itemRect) ; 


ShowWindow (spellDialog) ; {show dialog box with default button outlined} 
REPEAT 
ModalDialog(@MyEventFilter, itemHit); {get events} 
IF itemHit = kAl1Caps THEN {user clicked Ignore Words in All Caps} 
BEGIN 


{get the control handle to the checkbox} 
GetDialogItem(spellDialog, kAll1Caps, itemType, itemHandle, 


itemRect) ; 
{get the last value of the checkbox} 
capsVal := GetControlValue (ControlHandle(itemHandle) ); 


{toggle the value of the checkbox} 
capsVal := 1 - capsVal; 
{set the checkbox to the new value} 
SetControlValue (ControlHandle(itemHandle), capsVal); 
END; 
IF itemHit = kSlang THEN {user clicked Ignore Slang Terms} 
BEGIN 
{get checkbox's handle, get its value, toggle it, then reset it} 
GetDialogItem(spellDialog, kSlang, itemType, itemHandle, itemRect); 





slangVal := GetControlValue (ControlHandle(itemHandle) ); 
slangVal := 1 - slangVal; 
SetControlValue (ControlHandle(itemHandle), slangVal); 
END; 
UNTIL ((itemHit = kSpellCheck) OR (itemHit = kCancel)); 
DisposeDialog(spellDialog) ; {close the dialog box} 
IF itemHit = kSpellCheck THEN {user clicked Spell Check button} 
BEGIN 
IF capsVal = 1 THEN {user wants to ignore all caps} 
ignoreCapsCheck := TRUE; 
IF slangVal = 1 THEN {user wants to ignore slang} 
ignoreSlangCheck := TRUE; 
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{now start the spell check} 

SpellCheckMyDoc (ignoreCapsCheck, ignoreSlangcheck) ; 
END; 
END; 





The MySpellCheckDialog routine calls ModalDialog immediately after using 
GetNewDialog to create and display the dialog box. The MySpel1CheckDialog 
routine repeatedly responds to events in the two checkboxes until the user clicks either 
the Spell Check or the Cancel button. When the user clicks either of the checkboxes 
(which are the third and fourth items in the item list resource), MySpel1lCheckDialog 
uses the Get DialogItem procedure to get a handle to the checkbox. The 
MySpellCheckDialog routine coerces this handle to a control handle and passes 

it to the Control Manager function Get Cont rolValue to get the last value of the 
control (1 if the checkbox was selected or 0 if it was unselected). Subtracting this 

value from 1, MySpel1CheckDialog derives a new value for the control. Then 
MySpellCheckDialog passes this value to the Control Manager procedure 
SetControlValue to set the new value. The Control Manager responds by drawing 
an X in the box if the value of the control is 1 or removing the X if the value of the 
control is 0. 


As soon as the user clicks the Spell Check or Cancel button (which are the first and 
second items in the item list resource), MySpel1CheckDialog stops responding to 
events in the checkboxes. This routine uses the DisposeDialog procedure (which is 
explained in “Closing Dialog Boxes” beginning on page 6-100) to remove the dialog box. 
If the user clicks the Cancel button, MySpe11CheckDialog does no further processing 
of the information in the dialog box. If, however, the user clicks the Spell Check button, 
MySpellCheckDialog calls another application-defined routine, Spel1CheckMyDoc, 
to check the document for spelling errors according to the preferences that the user 
communicated in the checkboxes. 


For events inside the dialog box, ModalDialog passes the event to an event filter 
function before handling the event. In this example, the application specifies a pointer to 
its own event filter function, MyEventFilter. As described in the next section, your 
application should provide an event filter function. You can use the same event filter 
function in most or all of your alert and modal dialog boxes. 


Unless your event filter function handles the event and returns TRUE, ModalDialog 
handles the event as follows: 


m In response to an activate or update event for the dialog box, ModalDialog activates 
or updates its window. 


m Ifthe user presses the mouse button while the cursor is in an editable text item, 
ModalDialog responds to the mouse activity as appropriate—that is, either by 
displaying an insertion point or by selecting text. If a key-down event occurs and 
there’s an editable text item, text entry and editing are handled as described in 
“Responding to Events in Editable Text Items” beginning on page 6-79. If the editable 
text item is enabled, ModalDialog returns its item number after it receives either the 
mouse-down or key-down event. Normally, editable text items are disabled, and you 
use the GetDialogItemText procedure to read the information in the items only 
after the user clicks the OK button. Listing 6-12 on page 6-49 illustrates this technique. 
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m Ifthe user presses the mouse button while the cursor is in a control, ModalDialog 
calls the Control Manager function TrackCont rol. If the user releases the mouse 
button while the cursor is in an enabled control, ModalDialog returns the control’s 
item number. Your application should respond appropriately; for example, Listing 
6-26 uses an application-defined routine that checks the spelling of a document when 
the user clicks the Spell Check button. 


m Ifthe user presses the mouse button while the cursor is in any other enabled item in 
the dialog box, ModalDialog returns the item’s number, and your application should 
respond appropriately. Generally, only controls should be enabled. If your application 
creates a complex control—such as one that measures how far a dial is moved—your 
application must provide an event filter function to handle mouse events in that item. 


m Ifthe user presses the mouse button while the cursor is in a disabled item or in no 
item, or if any other event occurs, ModalDialog does nothing. 


Writing an Event Filter Function for Alert and Modal Dialog Boxes 


For alert and modal dialog boxes, the Dialog Manager provides a standard event filter 
function that checks whether the user has pressed the Enter or Return key and, if so, 
returns the item number of the default button. In early versions of Macintosh system 
software, when a single application controlled the computer, the standard event filter 
function for alert boxes and most modal dialog boxes was usually sufficient. However, 
because the standard event filter function does not permit background applications to 
receive or respond to update events, it is no longer sufficient. 


Thus, your application should provide a simple event filter function that performs these 
functions and also allows inactive windows to receive update events. You can use the 
same event filter function in most or all of your alert and modal dialog boxes. 


You can also use your event filter function to handle other events that ModalDialog 
doesn’t handle—such as the Command-period key-down event, disk-inserted events, 
keyboard equivalents, and mouse-down events (if necessary) for application-defined 

items that you provide. 


For example, the standard event filter function ignores key-down events for the 
Command key. When your application allows the user to access your menus after you 
display a dialog box, your event filter function should handle keyboard equivalents for 
menu commands and return TRUE. 


At a minimum, your event filter function should perform the following tasks: 


m retum TRUE and the item number for the default button if the user presses the Return 
or Enter key 


m retum TRUE and the item number for the Cancel button if the user presses the Esc key 
or the Command-period key combination 


m update your windows in response to update events (this also allows background 
applications to receive update events) and return FALSE 





m return FALSE for all events that your event filter function doesn’t handle 


You can also use the event filter function to test for and respond to keyboard equivalents 
and more complex events—for instance, the user dragging the cursor in an application- 
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defined item. For example, if you provide an application-defined item that requires you 
to measure how long the user holds down the mouse button or how far the user drags 
the cursor, use the event filter function to handle events inside that item. 


If it seems that you will spend time replicating much of your primary event loop in this 
event filter function, you might consider handling all the events in your main event loop 
instead of using the Dialog Manager’s Alert, NoteAlert, StopAlert, and 
CautionAlert functions or ModalDialog procedure. 


Your own event filter function should have three parameters and return a Boolean value. 
For example, this is how to declare an event filter function named MyEventFilter: 





FUNCTION MyEventFilter (theDialog: DialogPtr; 
VAR theEvent: EventRecord; 
VAR itemHit: Integer): Boolean; 


After receiving an event that it does not handle, your function should return FALSE. 
When your function returns FALSE, ModalDialog handles the event, which you pass 
in the parameter theEvent. (Your function can also change the event to simulate a 
different event and return FALSE, which passes the altered event to the Dialog Manager 
for handling.) If your function does handle the event, your function should return TRUE 
as a function result and, in the itemHit parameter, the number of the item that it 
handled. The ModalDialog procedure and, in turn, the Alert, NoteAlert, 
StopAlert, and CautionAlert functions then return this item number in their own 
itemHit parameter. 





Because ModalDialog calls the GetNextEvent function with a mask that excludes 
disk-inserted events, your event filter function can call the Event Manager procedure 
Set SystemEventMask to accept disk-inserted events. See the chapter “Event Manager” 
in this book for a discussion about handling disk-inserted events. 





For alert and modal dialog boxes, the Dialog Manager provides a standard event filter 
function that checks whether the user has pressed the Enter or Return key and, if so, 
returns the item number of the default button. Your event filter function should always 
check whether the Return key or Enter key was pressed and, if so, return the item 
number of the default button in the itemHit parameter and a function result of TRUE. 
Your event filter function should also check whether the Esc key was pressed and, if so, 
return the item number for the Cancel button in the itemHit parameter and a function 
result of TRUE. Your event filter function should also respond to the Command-period 
key-down event as if the user had clicked the Cancel button. 








To give visual feedback indicating which item has been selected, you should invert 
buttons that are activated by keyboard equivalents for all alert and dialog boxes. A 
good rule of thumb is to invert a button for 8 ticks, long enough to be noticeable but 
not so long as to be annoying. The Control Manager performs this action whenever 

a user clicks a button, and your application should do this whenever a user presses the 
keyboard equivalent of a button click. 


For modal dialog boxes that contain editable text items, your application should handle 
menu bar access to allow use of your Edit menu and its Cut, Copy, Paste, Clear, and 
Undo commands, as explained in “Adjusting Menus for Modal Dialog Boxes” beginning 
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on page 6-68. Your event filter function should then test for and handle mouse-down 
events in the menu bar and key-down events for keyboard equivalents of Edit menu 
commands. Your application should respond to users’ choices from the Edit menu by 
using the procedures DialogCut, DialogCopy, DialogPaste, and DialogDelete to 
support the Cut, Copy, Paste, and Clear commands. 


Listing 6-27 shows MyEventFilter, which begins by handling update events in 
windows other than the alert or dialog box. (By responding to update events for your 
application’s own inactive windows in this way, you allow ModalDialog to perform 
a minor switch when necessary so that background applications can update their 
windows, too.) 


Next, MyEventFilter handles activate events. This event filter function then handles 
key-down events for the Return and Enter keys as if the user had clicked the default 
button, and it handles key-down events for the Esc key as if the user had clicked the 
Cancel button. (See Inside Macintosh: Text for information about character codes for the 
Return, Enter, and Esc keys.) Your event filter function can then include tests for other 
events, such as disk-inserted events and keyboard equivalents. 


Listing 6-27 A typical event filter function for alert and modal dialog boxes 


FUNCTION MyEventFilter(theDialog: DialogPtr; 











VAR theEvent: EventRecord; 
VAR itemHit: Integer): Boolean; 
VAR 
key: Char; 
itemType: Integer; 
itemHandle: Handle; 
itemRect: Rect; 
finalTicks: LongInt; 
BEGIN 
MyEventFilter := FALSE; {assume Dialog Mgr will handle it} 


IF (theEvent.what = 


(WindowPtr (theEvent .message) 


AND 
<> theDialog) 


updateEvt) 








THEN 








DoUpdate (WindowPtr (theEvent .message) ) 
ELSE IF (theEvent.what = AND 
<> theDialog) THEN 
DoActivate (WindowPtr (theEvent.message) , 





activateEvt) 











{update the window behind} 





(WindowPtr (theEvent .message) 








(BAnd(theEvent.modifiers, activeFlag) <> 0), theEvent) 
ELSE 
CASE theEvent.what OF 
keyDown, autoKey: {user pressed a key} 
BEGIN 
key := Char (BAnd(theEvent.message, charCodeMask) ); 
IF (key = Char(kReturnKey)) OR (key = Char(kEnterKey)) THEN 
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BEGIN {respond as if user clicked Spell Check} 
GetDialogItem(theDialog, kSpellCheck, itemType, itemHandle, 
itemRect) ; 
{invert the Spell Check button for user feedback} 
HiliteControl (ControlHandle(itemHandle), inButton); 
Delay (kVisualDelay, finalTicks); {invert button for 8 ticks} 
HiliteControl (ControlHandle(itemHandle), 0); 
myEventFilter := TRUE; {event's being handled} 
itemHit := kSpellCheck; {return the default button} 
END; 
IF (key = Char (kEscapeKey)) OR {user pressed Esc key} 
(Boolean (BAnd(theEvent.modifiers, cmdKey)) AND 
(key = Char(kPeriodKey))) THEN {user pressed Cmd-pd} 
BEGIN {handle as if user clicked Cancel} 
GetDialogItem(theDialog, kCancel, itemType, itemHandle, 

















itemRect) ; 
{invert the Cancel button for user feedback} 
HiliteControl (ControlHandle(itemHandle), inButton); 








Delay (kVisualDelay, finalTicks); {invert button for 8 ticks} 
HiliteControl (ControlHandle(itemHandle), 0); 
MyEventFilter := TRUE; {event's being handled} 
itemHit := kCancel; {return the Cancel button} 
ND; {of Cancel} 
{handle any other keyboard equivalents here} 


ea 





END; {of keydown, autokey} 
{handle disk-inserted and other events here, as needed} 
OTHERWISE 





END; {of CASE} 


To use this event filter function for an alert box, the application specifies a pointer to 
MyEventFilter when it calls one of the Alert functions, as shown in Listing 6-19 on 
page 6-66. To use this event filter function for a modal dialog box, the application 
specifies a pointer to MyEventFilter when it calls ModalDialog, as shown in 
Listing 6-26 on page 6-83. 





Responding to Mouse Events in Modeless and 
Movable Modal Dialog Boxes 


To handle events in modeless and movable modal dialog boxes, you can use the 
IsDialogEvent function to determine when events occur while a dialog box is the 
frontmost window. For such events, you can then use the DialogSelect function to 
handle key-down events in editable text items automatically, to handle update and 
activate events automatically, and to report the enabled items that the user clicks. You 
must also use additional Toolbox routines to handle other types of keyboard events and 
other events in the dialog box. 
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WARNING 
The IsDialogEvent and DialogSelect functions are unreliable 
when running in versions of system software previous to System 7. & 





Alternatively, and probably most efficiently, your application can respond to events in 
modeless and movable modal dialog boxes by first determining the type of event that 
occurred and then taking the appropriate action according to which type of window is 

in front. If a modeless or movable modal dialog box is in front, you can provide code 
that takes any actions specific to that dialog box. You can then use the DialogSelect 
function instead of the Control Manager functions FindControl and TrackControl 

to handle mouse events in your dialog boxes. The DialogSelect function also handles 
update events, activate events, and events in editable text items. (If your modeless or 
movable modal dialog box contains editable text items, you should call DialogSelect 
during null events to cause the text cursor to blink.) 


If you choose to determine whether events involve movable modal or modeless dialog 
boxes without the aid of the IsDialogEvent function, your application should be 
prepared to handle the following mouse events: 


m clicks in the menu bar, which your application has adjusted as appropriate for the 
dialog box. Be sure to use the procedures DialogCut, DialogCopy, DialogPaste, 
and DialogDelete to support the Cut, Copy, Paste, and Clear commands in editable 
text items in your dialog boxes. 


m clicks in the content region of an active movable modal or modeless dialog box. You 
can use the DialogSelect function to aid you in handling the event. 


m clicks in the content region of an inactive modeless dialog box. In this case, your 
application should make the modeless dialog box active by making it the front- 
most window. 


m clicks in the content region of an inactive window whenever a movable modal or 
modeless dialog box is active. For movable modal dialog boxes, your application 
should emit the system alert sound, whereas for modeless dialog boxes, your 
application should bring the inactive window to the front. 


m™ mouse-down events in the drag region (that is, the title bar) of an active movable 
modal or modeless dialog box. Your application should use the Window Manager 
procedure DragWindow to move the dialog box in response to the user’s actions. 


m mouse-down events in the drag region of an inactive window when a movable 
modal dialog box is active. Your application should not move the inactive window 
in response to the user’s actions. Instead, your application should play the system 
alert sound. 


m clicks in the close box of a modeless dialog box. Your application should dispose of or 
hide the modeless dialog box, whichever action is more appropriate. 


Figure 6-41 shows a simple modeless dialog box with editable text items. 


Listing 6-28 illustrates an application-defined procedure that handles mouse-down 
events for all windows, including the modeless dialog box shown in Figure 6-41. 
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Figure 6-41 A modeless dialog box for which DialogSelect reports events 





=> Global Changes 











Listing 6-28 Handling mouse-down events for all windows 


PROCEDURE DoMouseDown (event: EventRecord) ; 


VAR 
part: Integer; 
thisWindow: WindowPtr; 
BEGIN 
{find general location of the cursor at the time of mouse-down event} 
part := FindWindow(event.where, thisWindow) ; 
CASE part OF {take action based on the cursor location} 
inMenuBar: ; {cursor in menu bar; respond with Menu Manager routines} 
inSysWindow: ; {cursor in a DA; use SystemClick here} 
inContent: {cursor in the content area of one of this app's windows} 


IF thisWindow <> FrontWindow THEN 
BEGIN {mouse-down in a window other than the front } 
{ window--make the clicked window the front window, } 
{ unless the front window is a movable modal dialog box} 


IF MyIsMovableModal (FrontWindow) THEN 
SysBeep (30) {emit system alert sound} 
ELSE 





SelectWindow (thisWindow) ; 


END 
ELSE {mouse-down in the content area of front window} 


DoContentClick (thisWindow, event); 


inDrag: {handle mouse-down in drag area} 
IF (thisWindow <> FrontWindow) AND (MyIsMovableModal (FrontWindow) ) 
THEN 
SysBeep (30) {emit system alert sound} 
ELSE 
DragWindow(thisWindow, event.where, GetGrayRgn**.rgnBBox) ; 
inGrow: ; {handle mouse-down in zoom box here} 
inGoAway: {handle mouse-down in close box here} 
IF TrackGoAway (thisWindow, event.where) THEN 
DoCloseCmd; 
inZoomIn, inZoomOut: ; {handle zoom box region for standard windows} 
END; {end of CASE} 
END; {of DoMouseDown } 
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The DoMouseDown routine first uses the Window Manager function FindWindow to 
determine approximately where the cursor is when the mouse button is pressed. When 
the user presses the mouse button while the cursor is in the content area of a window, 
DoMouseDown first checks whether the mouse-down event occurs in the currently active 
window by comparing the window pointer returned by FindWindow with that returned 
by the Window Manager function FrontWindow. 


When the mouse-down event occurs in an inactive window, DoMouseDown uses another 
application-defined routine, MyIsMovableModal, to check whether the active window 
is a movable modal dialog box. If so, DoMouseDown plays the system alert sound. 
Otherwise, DoMouseDown uses the Window Manager procedure Select Window 

to make the selected window active. (Although not illustrated in this book, the 
MyIsMovableModal routine uses the Window Manager function Get WVariant to 
determine whether the variation code for the front window is movableDBoxProc. If so, 
MyIsMovableModal returns TRUE.) See the chapter “Window Manager” in this book 
for more information about the SelectWindow and Get WVariant routines. 


As in this example, you must ensure that the movable dialog box is modal within your 
application. That is, the user should not be able to switch to another of your application’s 
windows while the movable modal dialog box is active. Instead, your application should 
emit the system alert sound. Notice as well that when the mouse-down event occurs in 
the drag region of any window, DoMouseDown checks whether the drag region belongs 
to an inactive window while a movable modal dialog box is active. If it does, 
DoMouseDown again plays the system alert sound. (However, by clicking other applica- 
tions’ windows or by selecting other applications from the Application and Apple 
menus, users should be able to switch your application to the background when you 
display a movable modal dialog box—an action users cannot perform with fixed- 
position modal dialog boxes.) 


If a user presses the mouse button while the cursor is in the content region of the active 
window, DoMouseDown calls another application-defined routine, DoContentClick, 
to further handle mouse events. Listing 6-29 shows how this routine in turn uses the 
DialogSelect function to handle the mouse-down event after the application 
determines that it occurs in the modeless dialog box shown in Figure 6-41 on page 6-91. 


Listing 6-29 Using the DialogSelect function for responding to mouse-down events 


PROCEDURE DoContentClick (thisWindow: windowPtr; event: EventRecord) ; 
VAR 

itemHit: Integer; 

refCon: Integer; 
BEGIN 

windowType := MyGetWindowType (thisWindow) ; 


CASE windowType OF 
kMyDocWindow: ; 
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kGlobalChangesID: {user clicked Global Changes dialog box} 
BEGIN 
IF DialogSelect (event, DialogPtr(thisWindow), itemHit) THEN 
BEGIN 
IF itemHit = kChange THEN {user clicked Change} 


; {use GetDialogItem and GetDialogItemText to get } 
{ the text strings and replace one string with the } 
{ other here} 
IF itemHit = kStop THEN {user clicked Stop} 
; {stop making changes here} 





END; 
END; {of CASE for kGlobalChangesID} 
{handle other window types here} 


END; {of CASE} 





In this example, when the user clicks the Change button, DialogSelect returns its 
item number. Within the user’s document, the application then performs a global search 
and replace. (Listing 6-12 on page 6-49 illustrates how an application can use the 
GetDialogItem and GetDialogItemText procedures for this purpose.) Generally, 
only controls should be enabled in a dialog box; therefore, your application normally 
responds only when DialogSelect returns TRUE after the user clicks an enabled 
control. For example, if the event is an activate or update event for a dialog box, 
DialogSelect activates or updates it and returns FALSE, so your application does not 
need to respond to the event. 


At this point, you may also want to check for and respond to any special events that you 
do not wish to pass to DialogSelect or that require special processing before you pass 
them to DialogSelect. You would need to do this, for example, if the dialog box needs 
to respond to disk-inserted events. 


IMPORTANT 


When DialogSelect calls TrackControl, it does not allow you to 
specify any action procedures necessary for a more complex control— 
for example, a control that measures how long the user holds down 

the mouse button or one that measures how far the user has moved 

an indicator. For instances like this, you can create a picture or an 
application-defined item that draws a control-like object; you must then 
test for and respond to those events yourself before passing events to 
DialogSelect. Or, you can use the Control Manager functions 
FindControl and TrackControl to process the mouse events inside 
the controls of your dialog box. « 


Listing 6-28 on page 6-91 calls one of its application-defined routines, DoCloseCmd, 
whenever the user clicks the close box of the active window. If the active window is a 
modeless dialog box, you might find it more efficient to hide the window rather than 
remove its data structures. Listing 6-30 shows how you can use the Window Manager 
routine HideWindow to hide the Global Changes modeless dialog box when the user 
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clicks its close box. The next time the user chooses the Global Changes command, the 
dialog box is already available, in the same location and with the same text selected as 
when it was last used. (Listing 6-20 on page 6-67 illustrates how first to create and later 
redisplay this modeless dialog box.) 


Listing 6-30 Hiding a modeless dialog box in response to a Close command 





PROCEDURE DoCloseCmd; 
VAR 
myWindow: WindowPtr; 
myData: MyDocRecHnd; 
windowType: Integer; 


BEGIN 
myWindow := FrontWindow; 
windowType := MyGetWindowType (myWindow) ; 


CASE windowType OF 
kMyGlobalChangesModelessDialog: 





HideWindow (myWindow) ; 
kMySpellModelessDialog: 
HideWindow (myWindow) ; 
kMyDocWindow: 
BEGIN 
myData := MyDocRecHnd (GetWRefCon (myWindow) ) ; 
MyCloseDocument (myData) ; 
END; {of kMyDocWindow case} 
kDAWindow: 
CloseDeskAcc (WindowPeek (myWindow) *.windowKind) ; 
END; {of CASE} 
END; 


Responding to Keyboard Events in Modeless and 
Movable Modal Dialog Boxes 
If you adopt the previously described strategy of determining—without the aid of the 


IsDialogEvent function—whether events involve movable modal or modeless dialog 
boxes, your application should be prepared to handle the following keyboard events: 





mg keyboard equivalents, such as Command-C to copy, to which your application should 
respond appropriately 

um key-down events for the Return and Enter keys, to which your application should 
respond as if the user had clicked the default button 


um key-down events for the Esc or Command-period keystrokes, to which your 
application should respond as if the user had clicked the Cancel button 


m key-down and auto-key events in editable text items, for which your application can 
use the DialogSelect function, which in turn calls TextEdit to handle keystrokes 
within editable text items automatically 
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Listing 6-31 illustrates how an application can check for keyboard equivalents whenever 
it receives key-down events. If the user holds down the Command key while pressing 
another key, the application calls another of its application-defined procedures, 
DoMenuCommand, which handles keyboard equivalents for menu commands. See the 
chapter “Menu Manager” in this book for an example of a DoMenuCommand procedure. 
Remember that when a movable modal dialog box or a modeless dialog box is active, 
your application should adjust the menus appropriately, and use the procedures 
DialogCut, DialogCopy, DialogPaste, and DialogDelete to support the Cut, 
Copy, Paste, and Clear commands in editable text items. 


Listing 6-31 Checking for key-down events involving the Command key 


PROCEDURE DoKeyDown (event: EventRecord) ; 








VAR 
key: Char; 
BEGIN 
key := CHR(BAnd(event.message, charCodeMask) ); 
IF BAnd(event.modifiers, cmdKey) <> 0 THEN 
BEGIN {Command key down} 
IF event.what = keyDown THEN 
BEGIN 
MyAdjustMenus; {adjust the menus as needed} 
DoMenuCommand (MenuKey (key) ) ; {handle the menu command} 
END; 
END 
ELSE 
MyHandleKeyDown (event) ; 
END; 





After determining that a key-down event does not involve a keyboard equivalent, 
Listing 6-31 calls another of its own routines, MyHandleKeyDown, which is shown 
in Listing 6-32. 


Listing 6-32 Checking for key-down events in a modeless dialog box 





PROCEDURE MyHandleKeyDown (event: EventRecord) ; 





VAR 
window: WindowPtr; 
windowType: Integer; 
BEGIN 
window := FrontWindow; 





{determine the type of window--document, modeless, etc. } 
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windowType := MyGetWindowType (window) ; 

IF windowType = kMyDocWindow THEN {key-down in doc window} 
BEGIN {handle keystrokes in document window here} 

END 

ELSE {key-down in modeless dialog box} 


MyHandleKeyDownInModeless (event, windowType) ; 





END; 


The MyHandleKeyDown routine determines what type of window is active when 
the user presses a key. If a modeless dialog box is the frontmost window, 
MyHandleKeyDown automatically calls another application-defined routine, 
MyHandleKeyDownInModeless, to respond to key-down events in modeless dialog 
boxes. The MyHandleKeyDownInModeless routine is shown in Listing 6-33. 


Listing 6-33 Responding to key-down events in a modeless dialog box 


PROCEDURE MyHandleKeyDownInModeless (event: EventRecord; windowType: Integer); 











VAR 
key: Char; 
itemType: Integer; 
itemHandle: Handle; 
itemRect: Rect; 
finalTicks: LongInt; 
handled: Boolean; 
item: Integer; 
theDialog: DialogPtr; 
BEGIN 
handled := FALSE; 
theDialog := FrontWindow; 
CASE windowType OF 
kGlobalChangesID: {key-down in Global Changes dialog box} 
BEGIN 
key := Char (BAnd(event.message, charCodeMask) ); 
IF (key = Char(kReturnKey)) OR (key = Char(kEnterKey)) THEN 
BEGIN {respond as if user clicked Change} 


GetDialogItem(theDialog, kChange, itemType, itemHandle, 


itemRect) ; 
{invert the Change button for 8 ticks for user feedback} 





HiliteControl (ControlHandle(itemHandle), inButton); 
Delay (kVisualDelay, finalTicks); 
HiliteControl (ControlHandle(itemHandle), 0); 
{use GetDialogItem and GetDialogItemText to get the text } 
{ strings and replace one string with the other here} 
handled := TRUE; {event's been handled} 
END; 
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IF (key = Char(kEscapeKey)) OR {user pressed Esc key} 
(Boolean (BAnd(event.modifiers, cmdKey)) AND 
(key = Char (kPeriodKey))) THEN {user typed Cmd-pd} 
BEGIN {handle as if user clicked Stop} 
GetDialogItem(theDialog, kStop, itemType, itemHandle, 





itemRect) ; 
{invert the Stop button for 8 ticks for user feedback} 

HiliteControl (ControlHandle(itemHandle), inButton); 

Delay (kVisualDelay, finalTicks); 

HiliteControl (ControlHandle(itemHandle), 0); 

{cancel the current operation here} 

handled := TRUE; {event's been handled} 
END; 
IF NOT handled THEN {let DialogSelect handle keydown events in } 

{ editable text items} 
handled := DialogSelect (event, theDialog, item); 








END; {of case kGlobalChangesID} 
{handle other modeless and movable modal dialog boxes here} 


END; 
END; 


{of CASE} 





When MyHandleKeyDownInModeless determines that the front window is the Global 
Changes modeless dialog box, it checks whether the user pressed Return or Enter. If so, 
MyHandleKeyDownInModeless responds as if the user had clicked the default button: 
Change. The MyHandleKeyDownInModeless routine uses the Control Manager 
procedure HiliteControl to highlight the Change button for 8 ticks. (Listing 6-27 on 
page 6-88 illustrates how to use HiliteControl to highlight the button from within a 
modal dialog box’s event filter function.) 


When the user presses Esc or Command-period, MyHandleKeyDownInModeless 
responds as if the user had clicked the Cancel button. 


Finally, MyHandleKeyDownInModeless uses the DialogSelect function, which in 
turn calls TextEdit to handle keystrokes within editable text items. 


Responding to Activate and Update Events in Modeless and Movable 
Modal Dialog Boxes 


If you adopt the previously described strategy of determining—without the aid of the 
IsDialogEvent function—whether events involve movable modal or modeless dialog 
boxes, your application should be prepared to handle activate and update events for 
both movable modal and modeless dialog boxes. You can use DialogSelect to assist 
you in handling activate and update events. For faster performance, you may instead 
want to use the UpdateDialog function when handling update events. Both 
DialogSelect and UpdateDialog use the QuickDraw procedure SetPort to make 
the dialog box the current graphics port before redrawing or updating it. 
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You should use the Control Manager procedure HiliteControl to make the buttons 
and other controls inactive in a modeless or movable modal dialog box when you 
deactivate it. The HiliteControl procedure dims inactive buttons, radio buttons, 
checkboxes, and pop-up menus to indicate to the user that clicking these items has no 
effect while the dialog box is in the background. When you activate a modeless or 
movable modal dialog box again, you should use HiliteControl to make the controls 
active again. 


The application-defined DoAct ivateGlobalChangesDialog routine shown in 
Listing 6-34 illustrates how to use HiliteControl to make the Change button active 
when activating a modeless dialog box and how to make the Change and Stop buttons 
inactive when deactivating the dialog box. 


Listing 6-34 Activating a modeless dialog box 


PROCEDURE DoActivateGlobalChangesDialog (window: WindowPtr; 








event: EventRecord); 











VAR 
activate: Boolean; 
handled: Boolean; 
item: Integer; 
itemType: Integer; 
itemHandle: Handle; 
itemRect: Rect; 
BEGIN 
MyCheckEvent (event); {get a valid event record to pass to DialogSelect} 
activate := (BAnd(event.modifiers, activeFlag) <> 0); 
IF activate THEN {activate the modeless dialog box} 
BEGIN 
{highlight editable text} 
SelectDialogItemText (window, kFindText, 0, 32767); 
{make the Change button active (make the Stop button active } 
{ only during a change operation) } 
GetDialogItem(DialogPtr (window), kChange, itemType, itemHandle, 
itemRect) ; 
HiliteControl(ControlHandle(itemHandle), 0); {make Change active} 
{draw a bold outline around the newly activated Change button} 
MyDrawDefaultButtonOutline (DialogPtr (window), kChange) ; 
END 
ELSE {dim the Change and Stop buttons for a deactivate dialog box} 
BEGIN 
GetDialogItem(DialogPtr (window), kChange, itemType, itemHandle, 
itemRect) ; 
HiliteControl (ControlHandle(itemHandle), 255); {dim Change button} 
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{draw a gray outline around the newly dimmed Change button} 
MyDrawDefaultButtonOutline (DialogPtr (window), kChange) ; 
GetDialogItem(DialogPtr (window), kStop, itemType, itemHandle, 
itemRect) ; 
HiliteControl (ControlHandle(itemHandle), 255); {dim Stop button} 
END; 
{let Dialog Manager handle activate events} 


handled := DialogSelect (event, window, item); 
MyAdjustMenus; {adjust the menus appropriately} 
END; 


The DoActivateGlobalChangesDialog routine uses DialogSelect to handle 
activate events in the modeless dialog box. In response to an activate event, 
DialogSelect handles the event and returns FALSE. The DialogSelect function sets 
the current graphics port to the modeless dialog box whenever the user makes it active. 


Because DialogSelect expects three parameters, one of which must be an event 
record, DoActivateGlobalChangesDialog uses the application-defined routine 
MyCheckEvent to verify that the event is a valid event. If it’s not, MyCheckEvent 
creates and returns a valid event record for an activate event. 








Because DialogSelect doesn’t call any draw procedures for items in response to 
activate events, DoActivateGlobalChangesDialog calls the application-defined 
draw routine MyDrawDefaultButtonOut1line to draw either a black outline around 
the default button when activating the dialog box or a gray outline when deactivating it. 
The MyDrawDefaultButtonOut line routine is shown in Listing 6-17 on page 6-59. 


Because users can switch out of your application when you display a movable modal 
dialog box, your application must handle activate events for it, too. 


You can also use DialogSelect to handle update events. In response to an update 
event, DialogSelect calls the Window Manager procedure BeginUpdate, the Dialog 
Manager procedure DrawDialog to redraw the entire dialog box, and then the Window 
Manager procedure EndUpdate. However, a faster way to update the dialog box is to 
use the Updat eDialog procedure, which redraws only the update region of a dialog 
box. As shown in Listing 6-35, you should call BeginUpdate before using 
UpdateDialog, and then call EndUpdate 








Listing 6-35 Updating a modeless dialog box 


PROCEDURE DoUpdate (window: WindowPtr) ; 
VAR 
windowType: Integer; 
BEGIN 
windowType := MyGetWindowType (window) ; 
CASE windowType OF 
kMyDocWindow: 





i {update document windows here} 
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kMyGlobalChangesModelessDialog: 
BEGIN 
BeginUpdate (window) ; 








UpdateDialog(window, window’%.visRgn) ; 
EndUpdate (window) ; 
END; 
{handle cases for other window types here} 
END; {of CASE} 
END; 








Closing Dialog Boxes 


When you no longer need a dialog box, you can dispose of it by using either the 
CloseDialog procedure if you allocated the memory for the dialog box or the 
DisposeDialog procedure if you did not. Or, you can merely make it invisible by 
using the Window Manager procedure HideWindow. 


Generally, your application should not allocate memory for modal dialog boxes or 
movable modal dialog boxes, but it should allocate memory for modeless dialog boxes. 
Under these circumstances, your application should use DisposeDialog to dispose 
of either a fixed or movable modal dialog box when the user clicks the OK or Cancel 
button, and it should use CloseDialog to dispose of a modeless dialog box when the 
user clicks the close box or chooses Close from the File menu. 


You do not close alert boxes; the Dialog Manager does that for you automatically by 
calling the DisposeDialog procedure after the user responds to the alert box by 
clicking any enabled button. 


The CloseDialog procedure removes a dialog box from the screen and deletes it from 
the window list. It also releases the memory occupied by 


m the data structures associated with the dialog box (such as its structure, content, and 
update regions) 

m all the items in the dialog box (except for pictures and icons, which might be shared 
by other resources) and any data structures associated with them—for example, the 
region occupied by the scroll box of a scroll bar 


The CloseDialog procedure does not dispose of the dialog record or the item list 
resource. Unlike GetNewDialog, NewDialog does not use a copy of the item list 
resource. So, if you create a dialog box with NewDialog, you may want to use 
CloseDialog to keep the item list resource in memory even if you didn’t supply a 
pointer to the memory. 


The DisposeDialog procedure calls CLloseDialog and, in addition, releases the 
memory occupied by the dialog’s item list resource and the dialog record. If you passed 
NIL as a parameter to GetNewDialogorNewDialog to let the Dialog Manager allocate 
memory in the heap, call DisposeDialog when you're done with a dialog box. 


For modeless and movable modal dialog boxes, you might find it more efficient to hide 
the dialog box rather than remove its data structures. Listing 6-30 on page 6-94 uses the 
Window Manager routine HideWindow to hide the Global Changes modeless dialog box 
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when the user clicks its close box. The next time the user invokes the Global Changes 
command, the dialog box is already available, in the same location and with the same 
text selected as when it was last used. 


If you adjust the menus when you display a dialog box, be sure to return them to an 
appropriate state when you close the dialog box, as described in “Adjusting Menus for 
Modal Dialog Boxes” beginning on page 6-68 and “Adjusting Menus for Movable Modal 
and Modeless Dialog Boxes” on page 6-73. 


Dialog Manager Reference 


This section describes the data structure, routines, and resources that are specific to the 
Dialog Manager. 


The “Data Structure” section shows the Pascal data structure for the dialog record, which 
the Dialog Manager creates and maintains. The “Dialog Manager Routines” section 
describes Dialog Manager routines for invoking alerts, creating and disposing of dialog 
boxes, manipulating items in alert and dialog boxes, and handling events in dialog boxes. 


The “Application-Defined Routines” section describes routines that your application 
must supply when you need to create application-defined items in dialog boxes, to filter 
events that the Dialog Manager doesn’t handle, and to define its own alert sounds. 


The “Resources” section describes the dialog resource, the alert resource, the item list 
resource, the dialog color table resource, the alert color table resource, and the item 
color table resource. The summary sections that conclude this chapter include listings 
of the constants that define values for the item types in alert and dialog boxes, the OK 
and Cancel buttons in alert boxes, and the icons in note alert boxes, caution alert boxes, 
and stop alert boxes, along with the constants used by the Gestalt function for the 
Dialog Manager. 


Data Structure 


This section describes the dialog record. Your application doesn’t need to create or use 
this record; rather, your application simply uses the appropriate Dialog Manager 
routines, creates any necessary resources, and then allows the Dialog Manager to create 
and use records of this data type as necessary. The dialog record is described here for 
completeness only. 


The Dialog Record 


To create an alert or a dialog box, you use a Dialog Manager routine—such as Alert or 
GetNewDialog—that incorporates information from your item list resource and from 
your alert resource or dialog resource into a data structure, called a dialog record, in 
memory. The Dialog Manager creates a dialog record, which is a data structure of type 
DialogRecord, whenever your application creates an alert or a dialog box. Your 
application generally should not create a dialog record or directly access its fields. 
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TYPE DialogPtr = WindowPtr; 
DialogPeek = “DialogRecord 
DialogRecord = 
RECORD 
window: WindowRecord; {dialog window} 
items: Handle; {item list resource} 
textH: TEHandle; {current editable text item} 
editField: Integer; {editable text item number } 
{ minus 1} 
editOpen: Integer; {used internally; reserved} 
aDefItem: Integer; {default button item number} 
END; 
Field descriptions 
window The window record for the alert box or dialog box. 
items A handle to the item list resource for the alert or the dialog box. 
textH A handle to the current editable text item. 
editField The current editable text item. 
editOpen Used internally; reserved. 
aDefItem The item number of the default button. 
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This section describes the routines for initializing the Dialog Manager, invoking alerts, 
creating and disposing of dialog boxes, manipulating items in alert and dialog boxes, 
and handling events in alert and dialog boxes. 


Some Dialog Manager routines can be accessed using more than one spelling of the 
routine’s name, depending on the interface files supported by your development 
environment. For example, GetDialogItem is also available as GetDItem. 
Table 6-1 provides a mapping between the previous name of a routine and its new 


equivalent name. 


Table 6-1 Mapping between new and previous names of Dialog Manager routines 
New name Previous name 

DialogCopy DlgCopy 

DialogCut DlgCut 

DialogDelete DlgDelete 

DialogPaste DigPaste 

DisposeDialog DisposDialog 

FindDialogItem FindDItem 
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Table 6-1 Mapping between new and previous names of Dialog Manager routines (continued) 
New name Previous name 
GetAlertStage GetAlrtStage 
GetDialogItem GetDItem 
GetDialogItemText Get IText 
HideDialogItem HideDItem 
NewColorDialog NewCDialog 
ResetAlertStage ResetAlrtStage 
SelectDialogItemText SelIText 
SetDialogFont SetDAFont 
SetDialogItem SetDItem 
SetDialogItemText SetIText 
ShowDialogItem ShowDItem 
UpdateDialog UpdtDialog 


Initializing the Dialog Manager 


Before using the Dialog Manager, you must initialize—in order—QuickDraw, the 
Font Manager, the Window Manager, the Menu Manager, and TextEdit. The first 
Dialog Manager routine to call is the InitDialogs procedure, which initializes 
the Dialog Manager. 


At your application’s request, the Dialog Manager uses the system alert sound for 
signaling the user during various alert stages. For alerts, if you want the Dialog Manager 
to play sounds other than the system alert sound, write your own sound procedure 
(described on page 6-144) and call the ErrorSound procedure to make it the current 
sound procedure. 





By default, the Dialog Manager displays static text and editable text items in the system 
font. To make it easier to localize your application for use with worldwide versions of 
system software, you should not change the font. However, if you determine that it is 
imperative for your application to display static text or editable text in a font other than 
the system font, you can use the SetDialogFont procedure. 


InitDialogs 


Use the InitDialogs procedure to initialize the Dialog Manager. 


PROCEDURE InitDialogs (resumeProc: ResumeProcPtr) ; 
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resumeProc 
A pointer to a procedure used by the System Error Handler in case a fatal 
system error occurs on a system that predates MultiFinder. For System 7, 
your application should set this parameter to NIL. 


Before using the Dialog Manager, you must initialize QuickDraw, the Font Manager, 

the Window Manager, the Menu Manager, and Textkdit, in that order. Then, to 

initialize the Dialog Manager, call InitDialogs once before all other Dialog Manager 
routines. The InitDialogs procedure does the following initialization: 


m Itsaves the pointer passed in the resumeProc parameter. For System 7, your 
application should set the resumeProc parameter to NIL. 


m It installs the system alert sound. To change the system alert sound, use the 
ErrorSound procedure. 





m It passes empty strings to the ParamText procedure. 


To use your own alert sound instead of the system alert sound for signaling the user, use 
the ErrorSound procedure. 

















PROCEDURE ErrorSound (soundProc: SoundProcPtr) ; 


soundProc A pointer to a procedure that generates the desired alert sounds. 


The Dialog Manager uses the system alert sound for signaling the user during various 
alert stages. The system alert sound, which is a sound resource stored in the System 
file, is played whenever system software or your application uses the Sound Manager 
procedure SysBeep. By changing the setting in the Sound control panel, the user can 
determine which sound is played. If you want to use sounds other than the system 
alert sound at various alert stages, write your own sound procedure and call the 
ErrorSound procedure to make it the current sound procedure. 
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If you pass NILin the soundProc parameter, the Dialog Manager neither plays sounds 
nor causes the menu bar to blink, and thus the user receives no signal. 


See the description of MyAlert Sound on page 6-144 for a discussion of how to write 
the sound procedure pointed to by the soundProc parameter. For examples of how to 
incorporate sound alerts into alert stages, see Listing 6-2 on page 6-21 and Listing 6-3 on 
page 6-22. 
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DESCRIPTION 


Although you generally should not change the font used in static and editable text items, 
you can do so with the SetDialogFont procedure. The SetDialogFont procedure is 
also available as the SetDAFont procedure. 


PROCEDURE SetDialogFont (fontNum: Integer); 


fontNum A font ID number. Do not rely on font number constants. Instead, use 
the Font Manager function Get FNum to find the font number to pass in 
this parameter. 


For subsequently created dialog and alert boxes, SetDialogFont sets the font of the 
dialog or alert box’s graphics port to the specified font. If you don’t call this procedure, 
the system font is used. The SetDialogFont procedure does not affect titles of controls, 
which are always displayed in the system font. 


SPECIAL CONSIDERATIONS 


There are a number of caveats regarding the SetDialogFont procedure. 


First, the Standard File Package does not always properly calculate the position of the 
standard file dialog box once this procedure has been called; for example, the standard 
file dialog box may be partially obscured by a menu bar. Second, be aware that this 
procedure affects all static text and editable text items in all of the alert and dialog boxes 
you subsequently display. Third, SetDialogFont does not change the font for control 
titles. Fourth, you can’t use SetDialogFont to change the font size or font style. 
Finally, and most importantly, your application will be much easier to localize if you 
always use the system font in your alert and dialog boxes and never use 
SetDialogFont. 


SEE ALSO 
See the chapter “Font Manager” in Inside Macintosh: Text for information about the 
GetFNum function. 

Creating Alerts 


To create an alert—consisting of an alert sound, an alert box, or both—use one of 
these functions: NoteAlert, CautionAlert, StopAlert, and Alert. The first 
three functions display, respectively, the note, caution, and stop alert icons (see 
Figure 6-3, Figure 6-4, and Figure 6-5) in the upper-left corner of the alert box. The 
Alert function allows you to display your own icon or to have no icon at all in the 
upper-left corner of your alert box. 
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These functions take descriptive information about the alert from an alert resource that 
you provide. When you call one of these functions, you pass it the resource ID of the 
alert resource and a pointer to an event filter function. These functions create a dialog 
record, play an alert sound, and display an alert box according to the alert stages that 
you specify in the alert resource. 


You should specify a pointer to an event filter function when you call the Alert, 
StopAlert, CautionAlert, and NoteAlert functions. You can use the same 
event filter function in most or all of your alert and modal dialog boxes. 


If you need to find out the current alert stage—for example, to ensure that your applica- 
tion deactivates the frontmost window only if an alert box is to be displayed at that 
stage—use the GetAlert Stage function. To change the current alert stage, use the 
ResetAlert Stage procedure. 


Your application does not dispose of alert boxes; the Dialog Manager does that for you 
automatically. 


Alert 


To display an alert box (or, if appropriate for the alert stage, to play an alert sound 
instead of or in addition to displaying the alert box), you can use the Alert function. 
This function does not display a default icon in the upper-left corner of the alert box; 
you can leave this area blank, or you can specify your own icon in the alert’s item list 
resource, which in turn is specified in the alert resource. 


FUNCTION Alert (alertID: Integer; 
filterProc: ModalFilterProcPtr): Integer; 


alertID The resource ID of an alert resource. If the alert resource is missing, the 
Dialog Manager returns to your application without creating the 
requested alert. 

filterProc 
A pointer to a function that responds to events not handled by the 
ModalDialog procedure. 


DESCRIPTION 
The Alert function creates the alert defined in the specified alert resource. The function 
calls the current alert sound procedure and passes it the sound number specified in the 
alert resource for the current alert stage. If no alert box is to be drawn at this stage, 
Alert returns —1; otherwise, it uses the NewDialog function to create and display the 
alert box. The default system window colors are used unless your application provides 
an alert color table resource with the same resource ID as the alert resource. 
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The Alert function uses the ModalDialog procedure, which repeatedly gets and 
handles most events for you. The ModalDialog procedure, in turn, gets each event by 
calling the Event Manager function GetNextEvent. If the event is a mouse-down event 
outside the content region of the alert box, ModalDialog emits an error sound and gets 
the next event. 





The Alert function continues calling ModalDialog until the user selects an enabled 
control (typically a button), at which time the Alert function removes the alert box from 
the screen and returns the item number of the selected control. Your application then 
responds as appropriate when the user clicks this item. 


For events inside the alert box, ModalDialog passes the event to an event filter function 
before handling the event. The event filter function provides a secondary event-handling 
loop for events that ModalDialog doesn’t handle. You specify a pointer to your event 
filter function in the filterProc parameter of the Alert function. 


If you set the £ilterProc parameter to NIL, the Dialog Manager uses the standard 
event filter function, which behaves as follows: 





m Ifthe user presses the Return or Enter key, the event filter function returns TRUE and 
returns the item number for the default button. 


However, your application should provide a simple event filter function that not only 
replicates this behavior but also 


m retums TRUE and the item number for the Cancel button if the user presses Esc or 
Command-period 


m updates your windows in response to update events (this also allows background 
windows to receive update events) and returns FALSE 





m returns FALSE for all events that your event filter function doesn’t handle 


You can also use the event filter function to test for and respond to keyboard equivalents. 





Unless the event filter function handles the event in its own way and returns TRUE, 
ModalDialog handles the event inside the alert box as follows: 


m Ifthe user presses the mouse button while the cursor is in a control, the Control 
Manager function TrackCont rol tracks the cursor. If the user releases the 
mouse button while the cursor is in an enabled control, Alert, StopAlert, 
CautionAlert, and NoteAlert remove the alert box and return the control’s 
item number. (Generally, buttons should be the only controls you use in alert boxes.) 


m Ifthe user presses the mouse button while the cursor is in any enabled item other than 
acontrol, Alert, StopAlert, CautionAlert, and NoteAlert remove the alert box 
and return the item number. (Generally, button controls should be the only enabled 
items in alert boxes.) 


m If user presses the mouse button while the cursor is in a disabled item or in no item, 
or if any other event occurs, Alert, StopAlert, CautionAlert, and NoteAlert 
do nothing. 
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The Alert function uses the QuickDraw routine Set Port to make the alert box the 
current graphics port. It’s not necessary for your application to call SetPort again 
before displaying alert boxes, because you can’t draw into any other windows between 
the time you create an alert box and the time the Dialog Manager displays it. 


SPECIAL CONSIDERATIONS 


SEE ALSO 
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If you need to display an alert box while your application is running in the background 
or is otherwise invisible to the user, you should use the Notification Manager to post a 
notification to the user. The Notification Manager automatically displays an alert box 
containing whatever message you specify; you will not need to use the Dialog Manager 
to create the alert box yourself. 


Note that the Notification Manager provides a one-way communications path from 
your application to the user. There is no provision for carrying information back from 
the user to your application while it is in the background (although it is possible for 
your application to determine if the notification was received). If you need to solicit 
information from the user, use the Notification Manager to inform the user to bring 
your application to the foreground, where the user can then respond to an alert box 
that your application presents. 


The ModalDialog procedure is described on page 6-135. See “Writing an Event Filter 
Function for Alert and Modal Dialog Boxes” beginning on page 6-86 for a discussion of 
how to write an event filter function. See “Creating Alert Sounds and Alert Boxes” 
beginning on page 6-18 for a discussion of alerts and alert stages. See “Titles for Buttons, 
Checkboxes, and Radio Buttons” beginning on page 6-37 and “Text Strings for Static Text 
and Editable Text Items” beginning on page 6-40 for recommendations about button 
titles and messages in alert boxes. Alert resources are described on page 6-150. Alert 
color table resources are described on page 6-157. The Dialog Manager uses the system 
alert sound as the error sound unless you change it by calling the ErrorSound pro- 
cedure, described on page 6-104. See “Responding to Events in Alert Boxes” beginning 
on page 6-81 for a discussion of how to respond to events returned by the Alert 
function. See the chapter “Notification Manager” in Inside Macintosh: Processes for 
information about the Notification Manager. 


The NoteAlert, CautionAlert, and StopAlert functions are identical to the Alert 
function, except that NoteAlert (described on page 6-110), CautionAlert (described 
on page 6-111), and StopAlert (described next) display icons in the upper-left corners 
of alert boxes. 
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To display an alert box with a stop icon in its upper-left corner (or, if appropriate for the 
alert stage, to play an alert sound instead of or in addition to displaying the alert box), 
use the StopAlert function. 


FUNCTION StopAlert (alertID: Integer; 
filterProc: ModalFilterProcPtr): Integer; 


alertID The resource ID of an alert resource. If the alert resource is missing, the 
Dialog Manager returns to your application without creating the 
requested alert. 

filterProc 
A pointer to a function that responds to events not handled by the 
ModalDialog procedure. If you set this parameter to NIL, the 
Dialog Manager uses the standard event filter function, which allows 
users to press the Return or Enter key in lieu of clicking the default 
button. However, your application should provide a simple event filter 
function that also allows background applications to receive update 
events. Pass a pointer to the event filter function in this parameter. 


The StopAlert function is the same as the Alert function except that, before drawing 
the items in the alert box, StopAlert draws the stop icon in the upper-left corner 
(within the rectangle with local coordinates [10,20,42,52]). The stop icon has the 
following resource ID: 


CONST stopIcon = 0; {stop icon} 


By default, the Dialog Manager uses the standard stop icon from the System file. You can 
change this icon by providing your own 'ICON"' resource with this resource ID number. 


Use a stop alert to inform the user that a problem or situation is so serious that the action 
cannot be completed. Stop alerts typically have only a single button (OK), because all the 
user can do is acknowledge that the action cannot be completed. 


Figure 6-5 on page 6-9 illustrates the stop icon in a typical stop alert. Except that it 
includes a stop icon in the alert box, StopAlert is identical to the Alert function. See 
the description of the Alert function on page 6-106 for detailed information about the 
parameters and behavior of both of these functions. 
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To display an alert box with a note icon in its upper-left corner (or, if appropriate for the 
alert stage, to play an alert sound instead of or in addition to displaying the alert box), 
use the NoteAlert function. 


FUNCTION NoteAlert (alertID: Integer; 
filterProc: ModalFilterProcPtr): Integer; 


alertID The resource ID of an alert resource. If the alert resource is missing, the 
Dialog Manager returns to your application without creating the 
requested alert. 

filterProc 
A pointer to a function that responds to events not handled by the 
ModalDialog procedure. If you set this parameter to NIL, the 
Dialog Manager uses the standard event filter function, which allows 
users to press the Return or Enter key in lieu of clicking the default 
button. However, your application should provide a simple event filter 
function that also allows background applications to receive update 
events. Pass a pointer to the event filter function in this parameter. 


The NoteAlert function is the same as the Alert function except that, before drawing 
the items in the alert box, NoteAlert draws the note icon in the upper-left commer 
(within the rectangle with local coordinates [10,20,42,52]). The note icon has the 
following resource ID: 


CONST notelIcon = 1; {note icon} 


By default, the Dialog Manager uses the standard note icon from the System file. You can 
change this icon by providing your own 'ICON"' resource with this resource ID number. 


Use a note alert to inform users of a minor mistake that won’t have any disastrous 
consequences if left as is. Usually this type of alert simply offers information, and the 
user responds by clicking an OK button. Occasionally, a note alert may ask a simple 
question and provide a choice of responses. 


Figure 6-3 on page 6-8 illustrates the note icon in a typical note alert. Except that it 
includes a note icon in the alert box, NoteAlert is identical to the Alert function. See 
the description of the Alert function on page 6-106 for detailed information about the 
parameters and behavior of both of these functions. 


Dialog Manager Reference 


CHAPTER 6 


Dialog Manager 


CautionAlert 


DESCRIPTION 


SEE ALSO 


To display an alert box with a caution icon in its upper-left corner (or, if appropriate for 
the alert stage, to play an alert sound instead of or in addition to displaying the alert 
box), use the CautionAlert function. 


FUNCTION CautionAlert (alertID: Integer; 
filterProc: ModalFilterProcPtr): Integer; 


alertID The resource ID of an alert resource. If the alert resource is missing, the 
Dialog Manager returns to your application without creating the 
requested alert. 

filterProc 
A pointer to a function that responds to events not handled by the 
ModalDialog procedure. If you set this parameter to NIL, the 
Dialog Manager uses the standard event filter function, which allows 
users to press the Return or Enter key in lieu of clicking the default 
button. However, your application should provide a simple event filter 
function that also allows background applications to receive update 
events. Pass a pointer to the event filter function in this parameter. 


The CautionAlert function is the same as the Alert function except that, before 
drawing the items in the alert box, CautionAlert draws the caution icon in the 
upper-left corner (within the rectangle with local coordinates [10,20,42,52]). The caution 
icon has the following resource ID: 


CONST cautionIcon = 2; {caution icon} 


By default, the Dialog Manager uses the standard caution icon from the System file. 
You can change this icon by providing your own 'ICON' resource with this resource 
ID number. 


Use a caution alert to alert the user of an operation that may have undesirable results if 
it’s allowed to continue. Give the user the choice of continuing the action (by clicking an 
OK button) or stopping it (by clicking a Cancel button). 


Figure 6-4 on page 6-9 illustrates the caution icon in a typical caution alert. Except 
that it includes a caution icon in the alert box, CautionAlert is identical to the 
Alert function. See the description of the Alert function on page 6-106 for detailed 
information about the parameters and behavior of both of these functions. 
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GetAlertStage 


DESCRIPTION 


To determine the stage of the last occurrence of an alert, use the GetAlertStage 
function. The GetAlertStage function is also available as the GetAlrt Stage function. 


FUNCTION GetAlertStage: Integer; 


The GetAlertStage function returns a number from 0 to 3 as the stage of the last 
occurrence of an alert. For example, you can use the GetAlert Stage function to 
ensure that your application deactivates the active window only if an alert box is to be 
displayed at that stage. 


ASSEMBLY-LANGUAGE INFORMATION 


SEE ALSO 


The global variable ACount contains this number. In addition, the global variable 
ANumber contains the resource ID of the alert resource of the last alert that occurred. 


Listing 6-19 on page 6-66 illustrates how to use GetAlert Stage to determine whether 
to deactivate a window for the current alert stage. Listing 6-2 on page 6-21 illustrates 
how to use an alert resource to specify different alert responses according to different 
alert stages. 


ResetAlertStage 


DESCRIPTION 


SEE ALSO 
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To reset the current alert stage to the first alert stage, use the ResetAlertStage 
procedure. The ResetAlert Stage procedure is also available as the 
ResetAlrtStage procedure. 














PROCEDURE ResetAlertStage; 


The ResetAlert Stage procedure resets every alert to a first-stage alert. 


Listing 6-2 on page 6-21 illustrates how to use an alert resource to specify different alert 
responses according to different alert stages. 
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Creating and Disposing of Dialog Boxes 


To create a dialog box, you should generally use the Get NewDialog function, which 
takes information about the dialog from a dialog resource in a resource file. Like window 
resources, dialog resources isolate descriptive information from your application code 
for ease of modification or translation to other languages. However, you can also use the 
NewDialog and NewColorDialog functions—for which you pass descriptive 
information in parameters—to create dialog boxes. 


The NewColorDialog function is identical to the NewDialog function, except that 
NewColorDialog returns a pointer to a color graphics port. 


When you no longer need a dialog box, use the CloseDialog procedure if 

you allocated the memory for the dialog record of the dialog box and use the 
DisposeDialog procedure if you did not. (To merely make the dialog box invisible 
to the user, you can use the Window Manager procedure HideWindow.) 


GetNewDialog 


DESCRIPTION 


To create a dialog box from a description in a dialog resource, use the GetNewDialog 
function. 


FUNCTION GetNewDialog (dialogID: Integer; dStorage: Ptr; 
behind: WindowPtr): DialogPtr; 


dialogID The resource ID of a dialog resource. If the dialog resource is missing, 
the Dialog Manager returns to your application without creating the 
dialog box. 


dStorage A pointer to the memory for the dialog record. If you set this parameter to 
NIL for modal dialog boxes and movable modal dialog boxes, the Dialog 
Manager automatically allocates memory for them in your application 
heap. For a modeless dialog box, however, you should allocate your 
own memory as you would for a window—otherwise, your heap could 
become fragmented. 


behind A pointer to the window behind which the dialog box is to be placed 
on the desktop. Always set this parameter to the window pointer 
Pointer (-1) to bring the dialog box in front of all other windows. 


The Get NewDialog function creates a dialog record from the information in the dialog 
resource and returns a pointer to it. You can use this pointer with Window Manager or 
QuickDraw routines to manipulate the dialog box. If the dialog resource specifies that 
the dialog box should be visible, the dialog box is displayed. If the dialog resource 
specifies that the dialog box should initially be invisible, use the Window Manager 
procedure ShowWindow to display the dialog box. 
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If you supply a dialog color table resource with the same resource ID as the dialog 
resource, GetNewDialog uses the NewColorDialog function and returns a pointer 
to a color graphics port. If no dialog color table resource is present, GetNewDialog 
uses NewDialog to return a pointer to a black-and-white graphics port, although 
system software draws the window frame using the system’s default colors. 


The dStorage and behind parameters of Get NewDialog have the same meaning as 
they do in the Window Manager function GetNewWindow. Always set the behind 
parameter to Pointer (—1) to bring the dialog box to the front. 


The dialog resource contains the resource ID of the dialog box’s item list resource. After 
calling the Resource Manager to read the item list resource into memory (if it’s not 
already in memory), GetNewDialog makes a copy of the item list resource and uses 
that copy; thus you may have several dialog boxes with identical items. 


If you provide a dialog color table resource, GetNewDialog copies it before passing it to 
the Window Manager routine SetWinColor unless the number-of-entries element of 
the dialog color table resource is set to -1, in which case the default window colors are 
used instead. The GetNewDialog function makes the copy so that the dialog color table 
resource can be purged without affecting the dialog box. 


SPECIAL CONSIDERATIONS 
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The Get NewDialog function doesn’t release the memory occupied by the resources. 
Therefore, your application should mark all resources used for a dialog box as purgeable. 


If either the dialog resource or the item list resource can’t be read, the function result is 
NIL; your application should test to ensure that NIL is not returned before performing 
any more operations with the dialog box or its items. 


For modal dialog boxes, the Dialog Manager function ModalDialog traps all events. 
This prevents your event loop from receiving activate events for your windows. Thus, 
if one of your application’s windows is active when you use GetNewDialog to create 

a modal dialog box, you must explicitly deactivate that window before displaying the 

modal dialog box. 


If you ever need to display a dialog box while your application is running in the back- 
ground or is otherwise invisible to the user, you should use the Notification Manager to 
post a notification to the user. The Notification Manager automatically displays an alert 
box containing whatever message you specify; you do not use the Dialog Manager to 
create the alert box yourself. 


Note that the Notification Manager provides a one-way communications path from 
your application to the user. There is no provision for carrying information back from 
the user to your application while it is in the background (although it is possible for 
your application to determine if the notification was received). If you need to solicit 
information from the user, use the Notification Manager to inform the user to bring 
your application to the foreground, where the user can then respond to the dialog box 
that your application presents. 


The GetNewDialog function uses either NewDialog or NewColorDialog, each of 
which generates an update event for the entire window contents. Thus, with the 
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exception of controls, items aren’t drawn immediately. The Dialog Manager calls the 
Control Manager to draw controls, and the Control Manager draws them immediately. 
So the controls won’t be drawn twice, the Dialog Manager calls the Window Manager 
procedure ValidRect for the enclosing rectangle of each control. If you find that there 
is too great a lag between the drawing of controls and the drawing of other items, try 
making the dialog box initially invisible and then calling the Window Manager 
procedure ShowWindow to show it. 


See “Creating Dialog Boxes” beginning on page 6-23 and “Displaying Alert and Dialog 
Boxes” beginning on page 6-61 for discussions and examples of how to use 
GetNewDialog. 


The Get NewWindow and ShowWindow procedures are described in the chapter 
“Window Manager” of this book. The Notification Manager is described in the 
chapter “Notification Manager” in Inside Macintosh: Processes. 


“Adjusting Menus for Modal Dialog Boxes” beginning on page 6-68 and “Adjusting 
Menus for Movable Modal and Modeless Dialog Boxes” on page 6-73 discuss menu 
adjustment when your application displays dialog boxes. See “Titles for Buttons, 
Checkboxes, and Radio Buttons” beginning on page 6-37 and “Text Strings for Static Text 
and Editable Text Items” beginning on page 6-40 for recommendations about messages 
and control titles in dialog boxes. 


NewColorDialog 


To create a dialog box, you can use the NewColorDialog function, which returns a 
pointer to a color graphics port. Generally, you should instead use Get NewDialog to 
create a dialog box, because Get NewDialog takes information about the dialog box 
from a dialog resource in a resource file. (Like window resources, dialog resources isolate 
descriptive information from your application code for ease of modification or transla- 
tion to other languages.) The NewColorDialog function is also available as the 
NewCDialog function. 


FUNCTION NewColorDialog (dStorage: Ptr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
procID: Integer; behind: WindowPtr; 
goAwayFlag: Boolean; refCon: LongInt; 
items: Handle): CDialogPtr; 


dStorage A pointer to the memory for the dialog record. If you set this parameter to 
NIL for modal dialog boxes and movable modal dialog boxes, the Dialog 
Manager allocates memory for them on your application heap. For a 
modeless dialog box, however, you should allocate your own memory 
as you would for a window—otherwise, your heap could become 
fragmented. 
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boundsRect 
A rectangle, given in global coordinates, that determines the size and 
position of the dialog box; these coordinates specify the upper-left and 
lower-right corners of the dialog box. 


title A text string used for the title of a modeless or movable modal dialog 
box. You can specify an empty string (not NIL) for a title bar that contains 
no text. 


visible A flag that specifies whether the dialog box should be drawn on the 
screen immediately. If you set this parameter to FALSE, the dialog box is 
not drawn until your application uses the Window Manager procedure 
ShowWindow to display it. 


procID The window definition ID for the type of dialog box. Use the dBoxProc 
constant to specify modal dialog boxes, the noGrowDocProc constant to 
specify modeless dialog boxes, and the movableDBoxProc constant to 
specify movable modal dialog boxes. 





behind A pointer to the window behind which the dialog box is to be placed on 
the desktop. Always set this parameter to the window pointer 
Pointer (-1) to bring the dialog box in front of all other windows. 


goAwayFlag 
A flag to specify whether a modeless dialog box should have a close box 
in its title bar when the dialog box is active. If you set this parameter to 
TRUE, the dialog window has a close box in its title bar when the window 
is active; only modeless dialog boxes should have close boxes. 


refCon A value that the Dialog Manager uses to set the refCon field of the 
dialog box’s window record. Your application may store any value here 
for any purpose. For example, your application can store a number that 
represents a dialog box type, or it can store a handle to a record that 
maintains state information about the dialog box. You 
can use the Window Manager procedure SetWRefCon at any time to 
change this value in the dialog record for a dialog box, and you can use 
the GetWRefCon function to determine its current value. 

items A handle to an item list resource for the dialog box. You can get the 
handle by calling the Resource Manager function Get Resource to read 
the item list resource into memory. Use the Memory Manager procedure 
HNoPurge to make the handle unpurgeable while you use it or use the 
Operating System utility function HandToHand to make a copy of the 
handle and use the copy. 


DESCRIPTION 


The NewColorDialog function creates a dialog box as specified by its parameters 
and returns a pointer to a color graphics port for the new dialog box. The first eight 
parameters (dStorage through refCon) are passed to the Window Manager function 
NewCWindow, which creates the dialog box. You can use this pointer with Window 
Manager or QuickDraw routines to manipulate the dialog box. 


The Dialog Manager uses the default window colors for the dialog box. By using the 
system's default colors, you ensure that your application’s interface is consistent with 
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that of the Finder and other applications. However, if you absolutely feel compelled to 
break from this consistency, you can use the Window Manager procedure SetWinColor 
to use your own dialog color table resource that specifies colors other than the default 
colors. Be aware, however, that nonstandard colors in your alert and dialog boxes may 
initially confuse your users. 


The Window Manager creates an auxiliary window record for the color dialog box. You 
can access this record with the Window Manager function GetAuxWin. (The 
dialogCItemhand_1e field of the auxiliary window record points to the dialog box’s 
item color table resource.) If the dialog box’s content color isn’t white, it’s a good idea 
to call NewColorDialog with the visible flag set to FALSE. After the color table 
and color item list resource are installed, use the Window Manager procedure 
ShowWindow to display the dialog box if it’s the frontmost window. If the dialog box 
is a modeless dialog box that is not in front, use the Window Manager procedure 
ShowHide to display it. 





When specifying the size and position of the dialog box in the boundsRect parameter, 
you should generally try to center dialog boxes between the left and right margins of the 
screen or the window where the user is working, whichever is more appropriate. Also 
ensure that the tops of dialog boxes (including the title bars of modeless and movable 
modal dialog boxes) lie below the menu bar when you position them on the main screen. 
You can use the Menu Manager function GetMBarHeight to determine the height of 

the menu bar. 


SPECIAL CONSIDERATIONS 


For modal dialog boxes, the Dialog Manager function ModalDialog traps all events. 
This prevents your event loop from receiving activate events for your windows. Thus, if 
one of your application’s windows is active when you use NewColorDialog to create 

a modal dialog box, you must explicitly deactivate that window before displaying the 
modal dialog box. 


If you ever need to display a dialog box while your application is running in the back- 
ground or is otherwise invisible to the user, you should use the Notification Manager 
to post a notification to the user. The Notification Manager automatically displays an 
alert box containing whatever message you specify; you do not need to use the Dialog 
Manager to create the alert box yourself. 


Note that the Notification Manager provides a one-way communications path from 
your application to the user. There is no provision for carrying information back from 
the user to your application while it is in the background (although it is possible for 
your application to determine if the notification was received). If you need to solicit 
information from the user, use the Notification Manager to inform the user to bring 
your application to the foreground, where the user can then respond to the dialog box 
that your application presents. 


The NewColorDialog function generates an update event for the entire window 
contents. Thus, with the exception of controls, items aren’t drawn immediately. The 
Dialog Manager calls the Control Manager to draw controls, and the Control Manager 
draws them immediately. So that the controls won’t be drawn twice, the Dialog Manager 
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calls the Window Manager procedure ValidRect for the enclosing rectangle of each 
control. If you find that there is too great a lag between the drawing of controls and the 
drawing of other items, try making the dialog box initially invisible and then calling the 
Window Manager procedure ShowWindow to show it. 


Window Manager routines are described in the chapter “Window Manager” in this book. 
The Notification Manager is described in the chapter “Notification Manager” in Inside 
Macintosh: Processes. See Inside Macintosh: Memory for a description of HNoPurge. See 
Inside Macintosh: Operating System Utilities for a description of HandToHand. 


“Adjusting Menus for Modal Dialog Boxes” beginning on page 6-68 and “Adjusting 
Menus for Movable Modal and Modeless Dialog Boxes” on page 6-73 discuss menu bar 
adjustment when your application displays dialog boxes. See “Titles for Buttons, 
Checkboxes, and Radio Buttons” beginning on page 6-37 and “Text Strings for Static Text 
and Editable Text Items” beginning on page 6-40 for recommendations about messages 
and control titles in dialog boxes. The Get Resource function is described in the chapter 
“Resource Manager” of Inside Macintosh: More Macintosh Toolbox. 


To create a dialog box, you can use the NewDialog function, which returns a pointer to a 
black-and-white graphics port (although system software draws the window frame of 
the dialog box using the system’s default window colors). Generally, you should instead 
use Get NewDialog to create a dialog box; Get NewDialog takes information about the 
dialog from a dialog resource in a resource file. (Like window resources, dialog resources 
isolate descriptive information from your application code for ease of modification or 
translation to other languages.) 


The NewDialog function is identical to the NewColorDialog function, except that 
NewDialog returns a pointer to a black-and-white graphics port. See the discussion 
of NewColorDialog on page 6-115 for descriptions of the parameters that you also 
pass to NewDialog. 


FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
procID: Integer; behind: WindowPtr; 








goAwayFlag: Boolean; refCon: LongInt; 
items: Handle): DialogPtr; 


The NewDialog function creates a dialog box as specified by its parameters and returns 
a pointer to a black-and-white graphics port for the new dialog box. The first eight 
parameters (dStorage through refCon) are passed to the Window Manager function 
NewWindow, which creates the dialog box. 
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When specifying the size and position of the dialog box in the boundsRect parameter, 
you should generally try to center dialog boxes between the left and right margins of the 
screen or the window where the user is working, whichever is more appropriate. Also 
ensure that the tops of dialog boxes (including the title bars of modeless and movable 
modal dialog boxes) lie below the menu bar when you position them on the main screen. 
You can use the Menu Manager function GetMBarHeight to determine the height of the 
menu bar. 


If you use a dialog color table resource to change the default window colors, use the 
NewColorDialog function, which returns a pointer to a color graphics port. See the 
description of NewColorDialog on page 6-115 for additional information common to 
both the NewDialog and NewColorDialog functions. 


CloseDialog 


DESCRIPTION 


To dismiss a dialog box for whose dialog record you allocated memory, use the 
CloseDialog procedure. 


PROCEDURE CloseDialog (theDialog: DialogPtr); 


theDialog A pointer toa dialog record. 


The CloseDialog procedure removes a dialog box from the screen and deletes it from 
the window list. The CloseDialog procedure releases the memory occupied by 


m the data structures associated with the dialog box (such as its structure, content, and 
update regions) 


m all the items in the dialog box (except for pictures and icons, which might be shared 
by other resources) and any data structures associated with them 


Generally, you should provide memory for the dialog record of modeless dialog boxes 
when you create them. (You can let the Dialog Manager provide memory for modal and 
movable modal dialog boxes.) You should then use CloseDialog to close a modeless 
dialog box when the user clicks the close box or chooses Close from the File menu. 


Because CloseDialog does not dispose of the dialog resource or the item list 

resource, it is important to make these resources purgeable. Unlike GetNewDialog, 
NewColorDialog does not use a copy of the item list resource. Thus, if you 

use NewColorDialog to create a dialog box, you may want to use CloseDialog to 
keep the item list resource in memory even if you didn’t supply a pointer to the memory. 
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If you let the Dialog Manager allocate memory for the dialog box (by passing NIL in the 
dStorage parameter to the GetNewDialog, NewColorDialog, orNewDialog 
function), use the DisposeDialog procedure, described next, instead of CloseDialog. 


DisposeDialog 


DESCRIPTION 


SEE ALSO 


To dismiss a dialog box for which the Dialog Manager supplies memory, use the 
DisposeDialog procedure. The DisposeDialog procedure is also available 
as the DisposDialog procedure. 


PROCEDURE DisposeDialog (theDialog: DialogPtr); 


theDialog A pointer toa dialog record. 


The DisposeDialog procedure calls the CloseDialog procedure and, in addition, 
releases the memory occupied by the dialog box’s item list resource and the dialog 
record. Call DisposeDialog when you’re done with a dialog box if you pass NIL in 
the dStorage parameter to GetNewDialog, NewColorDialog, orNewDialog. 


Generally, your application should not allocate memory for the dialog records of modal 
dialog boxes or movable modal dialog boxes. In these cases your application should use 
DisposeDialog when the user clicks the OK or Cancel button. 


If you allocate memory for the dialog box (for example, by passing a pointer in the 
dStorage parameter to the GetNewDialog, NewColorDialog, orNewDialog 
function), use CloseDialog, described on page 6-119, instead of DisposeDialog. 


Manipulating Items in Alert and Dialog Boxes 
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In many cases, you won't have to make any changes to alert or dialog boxes after you 
define them in the resource file. If you do need to make changes, use the Dialog Manager 
routines described in this section. 


For most item manipulation, first call the GetDialogItem procedure to get the 
information about the item. You can then use other routines to manipulate that item. Use 
the SetDialogItem procedure if you use any of these other routines to change the 
item. You must also use SetDialogItem to install any of your own application-defined 
draw procedures. If you use SetDialogItem, make the dialog box initially invisible, 
change the item as appropriate, then make the dialog box visible by using the Window 
Manager procedure ShowWindow. (For information about manipulating text in an 

alert box or a dialog box, see “Handling Text in Alert and Dialog Boxes” beginning on 
page 6-129.) 
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You can dynamically add items to and remove items from a dialog box by using the 
AppendDITL and ShortenDITL procedures. These procedures are especially useful 
if you share a single item list resource among multiple dialog boxes, because you can 
then use AppendDITLor ShortenDITL to add or remove items as appropriate for 
individual dialog boxes. You typically make such dialog boxes invisible, use the 
AppendDITL and ShortenDITL procedures as appropriate, then make the dialog 
boxes visible by using the Window Manager procedure ShowWindow. 


GetDialogItem 


To get a handle to an item so that you can manipulate it (for example, to determine its 
current value, to change it, or to install a pointer to a draw procedure for an 
application-defined item), use the GetDialogItem procedure. The GetDialogItem 
procedure is also available as the Get DIt em procedure. 











PROCEDURE GetDialogItem (theDialog: DialogPtr; itemNo: Integer; 
VAR itemType: Integer; VAR item: Handle; 
VAR box: Rect); 





theDialog A pointer to a dialog record. 


itemNo A number corresponding to the position of an item in the dialog box’s 
item list resource. 


itemType A value that represents the type of item requested in the itemNo 
parameter. You can use any of these constants to determine the value 
returned in this parameter: 


CONST 

ctrlitem = 4; {add this constant to the next } 

{ four constants} 

btnCtrl = 0; {standard button control} 
chkCtrl = 1; {standard checkbox control} 
radctrl = 2; {standard radio button} 
resCtrl = 3; {control defined in a 'CNTL'} 
helpiItem = 1; {help balloons} 

statText = 8; {static text} 

editText = 16; {editable text} 

iconItem = 323 {icon} 

picItem = 64; {QuickDraw picture} 

userItem = 0; {application-defined item} 


itemDisable = 128; {add to any of the above to } 
{ disable it} 
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item For an application-defined draw procedure, a pointer to the draw 
procedure (coerced to a handle), returned for the item specified in the 
itemNo parameter; for all other item types, a handle to the item. 

box The display rectangle (described in coordinates local to the dialog box), 
returned for the item specified in the itemNo parameter. 


The GetDialogItem procedure returns in its parameters the following information 
about the item numbered itemNo in the item list resource of the specified dialog box: 

in the itemType parameter, the item type; in the item parameter, a handle to the item 
(or, for application-defined draw procedures, the procedure pointer); and in the box 
parameter, the display rectangle for the item. 


For most item manipulation, first use the GetDialogItem procedure to get the informa- 
tion about the item. You can then use other routines, such as Get DialogItemText and 
SetDialogItem, to determine and change the value of that item. 


Listing 6-12 on page 6-49 illustrates the use of GetDialogItem in conjunction with 
GetDialogItemText to retrieve the text entered by a user in an editable text item. 
Listing 6-16 on page 6-58 illustrates the use of GetDialogItem in conjunction with 
SetDialogItem to install the draw procedure for an application-defined item into 
a dialog box. Listing 6-26 on page 6-83 illustrates the use of GetDialogItem to 
determine the current value of a checkbox in a dialog box. 


SetDialogItem 
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After using the GetDialogItem procedure to get a handle to an item from a dialog box, 
use the SetDialogItem procedure to set or change the item. The SetDialogItem 
procedure is also available as the SetDItem procedure. 


PROCEDURE SetDialogItem (theDialog: DialogPtr; itemNo: Integer; 
itemType: Integer; item: Handle; 
box: Rect); 





theDialog A pointer toa dialog record. 


itemNo A number corresponding to the position of an item in the dialog box’s 
item list resource. 


itemType A value that represents the type of item in the itemNo parameter. To 
specify the value for this parameter, you can use any of the constants 
listed on page 6-121 for the itemType parameter of the GetDialogItem 
procedure. 
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item For an application-defined item, a pointer to the draw procedure (coerced 
to a handle) for the item specified in the itemNo parameter; for all other 
item types, a handle to the item. 


box The display rectangle (described in coordinates local to the dialog box) for 
the item specified in the itemNo parameter. 


The SetDialogItem procedure sets the item specified by the it emNo parameter for the 
specified dialog box. This procedure installs the item without drawing it; typically you 
create an invisible dialog box, use SetDialogItem, then use the Window Manager 
procedure ShowWindow to draw the dialog box and its items. 


Listing 6-16 on page 6-58 illustrates how to use SetDialogItem to install an 
application-defined draw procedure. The ShowWindow procedure is described in the 
chapter “Window Manager” of this book. 


HideDialogItem 


DESCRIPTION 


Although you should rarely need to do so, you can make an item in a dialog box 
invisible by using the HideDialogItem procedure. The HideDialogItem procedure 
is also available as the HideDItem procedure. 





PROCEDURE HideDialogItem (theDialog: DialogPtr; itemNo: Integer); 


theDialog A pointer toa dialog record. 


itemNo A number corresponding to the position of an item in the dialog box’s 
item list resource. 


The HideDialogItem procedure hides the item specified by itemNo by giving ita 
display rectangle that’s off the screen. Specifically, if the left coordinate of the item’s 
display rectangle is less than 8192 (hexadecimal $2000), HideDialogItem adds 16,384 
(hexadecimal $4000) to both the left and right coordinates of the rectangle. If the item is 
already hidden (that is, if the left coordinate is greater than 8192), HideDialogItem 
does nothing. To redisplay an item that’s been hidden by HideDialogItem, you can 
use the ShowDialogItem procedure. 
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SPECIAL CONSIDERATIONS 


If your application needs to display a number of dialog boxes that are similar except for 
one or two items, it’s generally easier to modify the common elements using the 
AppendDITL and ShortenDITL procedures than to use the HideDialogItem and 
ShowDialogItem procedures. 


The rectangle for a static text item must always be at least as wide as the first character of 
the text. 


You generally shouldn’t use HideDialogItem to make an editable text item invisible, 
because as the user presses the Tab key, the Dialog Manager attempts to move the cursor 
to the hidden editable text item, where the user’s subsequent keystrokes will be placed. 


ShowDialogItem 


DESCRIPTION 
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To redisplay an item that has been hidden by the HideDialogItem procedure, use the 
ShowDialogItem procedure. The ShowDialogItem procedure is also available as the 
ShowDItem procedure. 








PROCEDURE ShowDialogItem (theDialog: DialogPtr; itemNo: Integer); 








theDialog A pointer toa dialog record. 


itemNo A number corresponding to the position of an item in the dialog box’s 
item list resource. 


The ShowDialogItem procedure redisplays the item specified in itemNo by restoring 
the display rectangle the item had prior to the HideDialogItem call. Specifically, if 
the left coordinate of the item’s display rectangle is greater than 8192, ShowDialogItem 
subtracts 16,384 from both the left and right coordinates of the rectangle. If the item 

is already visible (that is, if the left coordinate is less than 8192), ShowDialogItem 
does nothing. 


The ShowDialogItem procedure adds the rectangle that contained the item to the 
update region so that it will be drawn. Note that if the item is a control you define in a 
control ('CNTL"') resource, the rectangle added to the update region is the rectangle 
defined in the control resource, not the display rectangle defined in the item list resource. 
If the item is an editable text item, ShowDialogItem activates it by calling the TextEdit 
procedure TEActivate. 
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FindDialogItem 


DESCRIPTION 


To determine the item number of an item at a particular location in a dialog box, use the 
FindDialogItem function. The FindDialogItem function is also available as the 
FindDItem function. 


FUNCTION FindDialogItem (theDialog: DialogPtr; thePt: Point) 
Integer; 


theDialog A pointer to a dialog record. 


thePt A point, specified in coordinates local to the dialog box. 


If the point specified in the parameter thePt lies within an item, FindDialogItem 
returns a number corresponding to the position of that item in the dialog box’s item list 
resource. If the point doesn’t lie within the item’s rectangle, FindDialogItem returns 
-1. If items overlap, FindDialogItem returns the item number of the first item, in the 
item list resource, containing the point. 


This function is useful for changing the cursor when it’s over a particular item. 


The FindDialogItem function returns 0 for the first item in the item list resource, 
1 for the second, and so on. To get the proper item number before calling the 
GetDialogItem or SetDialogItem procedure, add 1 to FindDialogItem’s 
function result, as shown here: 


theItem := FindDialogItem(theDialog, thePoint) + 1; 


Note that FindDialogItem returns the item number of disabled items as well as 
enabled items. 


AppendDITL 


To add items to an existing dialog box while your application is running, use the 
AppendDITL procedure. 


PROCEDURE AppendDITL (theDialog: DialogPtr; theDITL: Handle; 
theMethod: DITLMethod) ; 


theDialog A pointer toa dialog record. This is the dialog record to which you will 
add the item list resource specified in the parameter theDITL. 


theDITL A handle to the item list resource whose items you want to append to the 
dialog box. 
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theMethod The manner in which you want the new items to be displayed in the 
existing dialog box. You can pass a negative value to offset the appended 
items from a particular item in the existing dialog box. You can also pass 
any of these constants: 


CONST 

overlayDITL = 0; {overlay existing items} 
appendDITLRight = LG {append at right} 
appendDITLBottom = ae {append at bottom} 





The AppendDITL procedure adds the items in the item list resource specified in the 
parameter theDITL to the items of a dialog box. This procedure is especially useful if 
several dialog boxes share a single item list resource, because you can use AppendDITL 
to add items that are appropriate for individual dialog boxes. Your application can use 
the Resource Manager function Get Resource to get a handle to the item list resource 
whose items you wish to add. 


In the parameter theMethod, you specify how to append the new items, as follows: 


m If you use the overlayDITL constant, AppendDITL superimposes the appended 
items over the dialog box. That is, AppendDITL interprets the coordinates of the 
display rectangles for the appended items (as specified in their item list resource) as 
local coordinates within the dialog box. 


mw Ifyou use the appendDITLRight constant, AppendDITL appends the items to the 
right of the dialog box by positioning the display rectangles of the appended items 
relative to the upper-right coordinate of the dialog box. The AppendDITL procedure 
automatically expands the dialog box to accommodate the new dialog items. 





m Ifyou use the appendDITLBottom constant, AppendDITL appends the items to the 
bottom of the dialog box by positioning the display rectangles of the appended items 
relative to the lower-left coordinate of the dialog box. The AppendDITL procedure 
automatically expands the dialog box to accommodate the new dialog items. 


m You can also append a list of items relative to an existing item by passing a negative 
number in the parameter theMet hod. The absolute value of this number is 
interpreted as the item in the dialog box relative to which the new items are to be 
positioned. For example, if you pass —2, the display rectangles of the appended 
items are offset relative to the upper-left corner of item number 2 in the dialog box. 


You typically create an invisible dialog box, call the AppendDITL procedure, then make 
the dialog box visible by using the Window Manager procedure ShowWindow. 


SPECIAL CONSIDERATIONS 
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The AppendDITL procedure modifies the contents of the dialog box (for instance, by 
enlarging it). To use an unmodified version of the dialog box at a later time, your 
application should use the Resource Manager procedure ReleaseResource to release 
the memory occupied by the appended item list resource. Otherwise, if your application 
calls AppendDITL to add items to that dialog box again, the dialog box remains 
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modified by your previous call—for example, it will still be longer at the bottom if you 
previously used the appendDITLBottom constant. 





The AppendDITL procedure is available in System 7 and in earlier versions of the 
Communications Toolbox. Before calling AppendDITL, you should make sure that it 

is available by using the Gestalt function with the gestaltDITLExtAttr selector. 
Test the bit indicated by the gestaltDITLExtPresent constant in the response 
parameter. If the bit is set, then AppendDITL is available. 


SEE ALSO 


Listing 6-13 on page 6-54 and Listing 6-14 on page 6-55 illustrate a typical use 

of AppendDITL. Figure 6-29 on page 6-52 shows the result of using the 
overlayDITL constant, Figure 6-30 on page 6-52 shows the result of using the 
appendDITLRight constant, Figure 6-31 on page 6-53 shows the result of using 
the appendDITLBottom constant, and Figure 6-32 on page 6-53 shows the result 
of using a negative number in the parameter theMethod. 


The chapter “Resource Manager” in Inside Macintosh: More Macintosh Toolbox describes 
the GetResource and ReleaseResource routines. The Gestalt function is 
described in the chapter “Gestalt Manager” of Inside Macintosh: Operating System Utilities. 
See the chapter “Window Manager” in this book for information about ShowWindow. 





ShortenDITL 


To remove items from an existing dialog box while your application is running, use the 
ShortenDITL procedure. 














PROCEDURE ShortenDITL (theDialog: DialogPtr; 
numberItems: Integer); 


theDialog A pointer to a dialog record. 

numberItems 
The number of items to remove (starting from the last item in the item 
list resource). 


DESCRIPTION 
The ShortenDITL procedure removes the specified number of items from the dialog 
box. This procedure is especially useful if several dialog boxes share a single item list 
resource, because you can use ShortenDITL to remove items as necessary for 
individual dialog boxes. 


You typically create an invisible dialog box, call the ShortenDITL procedure, then 
make the dialog box visible by using the Window Manager procedure ShowWindow. 
Note that ShortenDITL does not automatically resize the dialog box; you can use 
the Window Manager procedure Si zeWindow if you need to resize the dialog box. 
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SPECIAL CONSIDERATIONS 


The ShortenDITL procedure is available in System 7 and in earlier versions of the 
Communications Toolbox. Before calling ShortenDITL, you should make sure that it 
is available by using the Gestalt function with the gestaltDITLExtAttr selector. 
Test the bit indicated by the gestaltDITLExtPresent constant in the response 
parameter. If the bit is set, then ShortenDITL is available. 








SEE ALSO 


You can use the Count DITL function, described next, to determine the number of items 
in the dialog box’s item list resource. See the chapter “Window Manager” in this book 
for information on the ShowWindow and SizeWindow procedures. The Gestalt 
function is described in the chapter “Gestalt Manager” in Inside Macintosh: Operating 
System Utilities. 


CountDITL 


You can determine the number of items in a dialog box by using the CountDITL 
function. 


FUNCTION CountDITL (theDialog: DialogPtr): Integer; 


theDialog A pointer toa dialog record. 


DESCRIPTION 


The CountDITL function returns the number of current items in a dialog box. You 
typically use Count DITL in conjunction with ShortenDITL to remove items from a 
dialog box. 


SPECIAL CONSIDERATIONS 
The CountDITL function is available in System 7 and in earlier versions of the Commu- 
nications Toolbox. Before calling CountDITL, you should make sure that it is available 
by using the Gestalt function with the gestaltDITLExtAttr selector. Test the bit 
indicated by the gestalt DITLExtPresent constant in the response parameter. If the 
bit is set, then CountDITL is available. 


SEE ALSO 


The Gestalt function is described in the chapter “Gestalt Manager” in Inside Macintosh: 
Operating System Utilities. 
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Handling Text in Alert and Dialog Boxes 


ParamText 


DESCRIPTION 


The Dialog Manager provides several routines for manipulating text. You can use the 
ParamText procedure to supply text strings, such as document titles, dynamically 

in the static text items of alert and dialog boxes. The GetDialogItemText and 
SetDialogItemText procedures are useful for determining and changing text in both 
static text and editable text items. You can use the SelectDialogItemText procedure 
to select and highlight text in an editable text item. 


When a dialog box containing an editable text item is active, use the DialogCut 
procedure to handle the Cut editing command, the DialogCopy procedure to handle 
the Copy command, the DialogPaste procedure to handle the Paste command, and 
the DialogDelete procedure to handle the Clear command. 


Once you determine that an event occurs in a modeless or movable modal dialog box, 
you can use the DialogSelect function, which is described on page 6-139, to handle 
key-down events in editable text items automatically. The ModalDialog procedure 
uses DialogSelect to handle key-down events in the editable text items of modal 
dialog boxes. 


To substitute text strings in the static text items of your alert or dialog boxes while your 
application is running, use the ParamText procedure. 


PROCEDURE ParamText (param0: Str255; paraml: Str255; 
param2: Str255; param3: Str255); 





param0 A text string to substitute for the special string “0 in the static text items 
of all subsequently created alert and dialog boxes. 

paraml A text string to substitute for the special string *1 in the static text items 
of all subsequently created alert and dialog boxes. 

param2 A text string to substitute for the special string *2 in the static text items 
of all subsequently created alert and dialog boxes. 

param3 A text string to substitute for the special string *3 in the static text items 
of all subsequently created alert and dialog boxes. 


The ParamText procedure replaces the special strings *0 through *3 in the static text 
items of all subsequently created alert and dialog boxes with the text strings you pass as 
parameters. Pass empty strings (not NIL) for parameters not used. 


SPECIAL CONSIDERATIONS 


The strings used in ParamText are stored in the low-memory global variable 
DASt rings, which specifies a set of string handles used by the Dialog Manager. 
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If the user launches a desk accessory in your application’s partition and the desk 
accessory calls ParamText, it may change the text in your application’s dialog box. 


You should be very careful about using ParamText in modeless dialog boxes. If a 
modeless dialog box using ParamText is onscreen and you display another dialog box 
or alert box that also uses ParamText, both boxes will be affected by the latest call 
to ParamText. 


The strings you pass in the parameters to ParamText cannot contain the special strings 
“0 through *3, or else the procedure will enter an endless loop of substitutions in 
versions of system software earlier than 7.1. 


Note that you should try to store text strings in resource files to facilitate translation into 
other languages; therefore, ParamText is best used for supplying text strings, such as 
document names, that the user specifies. To avoid problems with grammar and sentence 
structure when you localize your application, you should use ParamText to supply 
only one text string per screen message. 


Listing 6-9 on page 6-47 and Listing 6-10 on page 6-48 show an example of how you can 
use ParamText to supply the title of the user’s current document to your alert and 
dialog boxes. If you need to supply a default text string to an editable text item while 
your application is running, use SetDialogItemText. The SetDialogItemText 
procedure also allows you to set or change the entire text string for a static text item. 


GetDialogItemText 


DESCRIPTION 


After using the GetDialogItem procedure to get a handle to an editable text item or a 
static text item in a dialog box, you can use the GetDialogItemText procedure to get 
the text string contained in that item. The GetDialogItemText procedure is also 
available as the Get IText procedure. 


PROCEDURE GetDialogItemText (item: Handle; VAR text: Str255); 


item A handle to an editable text item or a static text item in a dialog box. 


text The text contained within the item. 


The GetDialogItemText procedure returns, in the text parameter, the text of the 
given editable text or static text item. 


SPECIAL CONSIDERATIONS 
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If the user types more than 255 characters in an editable text item, 
GetDialogItemText returns only the first 255. 
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Listing 6-12 on page 6-49 illustrates how to use GetDialogItemText to retrieve 
the text that a user types into an editable text item. 


SetDialogItemText 


DESCRIPTION 


After using the GetDialogItem procedure to get a handle to an editable text item or 

a static text item in a dialog box, you can use the SetDialogItemText procedure to 
display a particular text string in that item. The SetDialogItemText procedure isalso 
available as the Set IText procedure. 














PROCEDURE SetDialogItemText (item: Handle; text: Str255); 


item A handle to an editable text item or a static text item in a dialog box. 


text The text to display in the item. 


The SetDialogItemText procedure places the specified text in the specified item and 
draws the item. This procedure is useful for supplying a default text string—such as a 
document name—for an editable text item while your application is running. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


All strings should be stored in resource files to ease translation into other languages. 


For static text items, the ParamText procedure, described on page 6-129, is useful when 
you need to determine and provide only a portion of a text string while your application 
is running. 


SelectDialogItemText 


To select and highlight text contained in an editable text item, use the 
SelectDialogItemText procedure. The SelectDialogItemText procedure 
is also available as the SelIText procedure. 





PROCEDURE SelectDialogItemText (theDialog: DialogPtr; 
itemNo: Integer; 











strtSel: Integer; 
endSel: Integer); 
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theDialog A pointer toa dialog record. 


itemNo A number corresponding to the position of an editable text item in the 
dialog box’s item list resource. 

strtSel A number representing the position of the first character to begin 
selecting. 

endSel A number representing one position past the last character to be selected. 


If the item in the itemNo parameter is an editable text item that contains text, the 
SelectDialogItemText procedure sets the text selection range to extend from 

the character position specified in the st rt Sel parameter up to but not including the 
character position specified in the endSel parameter. The selection range is highlighted 
unless st rt Sel equals endSe1, in which case a blinking vertical bar is displayed to 
indicate an insertion point at that position. If the editable text item doesn’t contain text, 
SelectDialogItemText displays the insertion point. 


You can select the entire text by specifying the number 0 in the strt Sel parameter and 
the number 32767 in the endSel parameter. 


For example, if the user makes an unacceptable entry in the editable text item, your 
application can display an alert box reporting the problem and then use 
SelectDialogItemText to select the entire text so it can be replaced by a new 
entry. Without this procedure, the user would have to select the item before making 
the new entry. 


For details about text selection range and character position, see the chapter “TextEdit” 
in Inside Macintosh: Text. 


When a dialog box containing an editable text item is active, use the DialogCut 
procedure to handle the Cut editing command. The DialogCut procedure is also 
available as the DlgCut procedure. 


PROCEDURE DialogCut (theDialog: DialogPtr); 


theDialog A pointer toa dialog record. 


The DialogCut procedure checks whether the dialog box has any editable text items 
and, if so, applies the TextEdit procedure TECut to the selected text. Your application 
should test whether a dialog box is the frontmost window when handling mouse-down 
events in the Edit menu and then call this routine when appropriate. 
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For more information about allowing access to your menus when your application 
displays dialog boxes, see “Adjusting Menus for Modal Dialog Boxes” beginning on 
page 6-68 and “Adjusting Menus for Movable Modal and Modeless Dialog Boxes” on 
page 6-73. The TECut procedure is described in the chapter “TextEdit” in Inside 
Macintosh: Text. 


DialogCopy 


DESCRIPTION 


SEE ALSO 


When a dialog box containing an editable text item is active, use the DialogCopy 
procedure to handle the Copy editing command. The DialogCopy procedure is also 
available as the DlgCopy procedure. 





PROCEDURE DialogCopy (theDialog: DialogPtr); 











theDialog A pointer to a dialog record. 


The DialogCopy procedure checks whether the dialog box has any editable text items 
and, if so, applies the TextEdit procedure TECopy to the selected text. Your application 
should test whether a dialog box is the frontmost window when handling mouse-down 
events in the Edit menu and then call this routine when appropriate. 


For more information about allowing access to your menus when your application 
displays dialog boxes, see “Adjusting Menus for Modal Dialog Boxes” beginning on 
page 6-68 and “Adjusting Menus for Movable Modal and Modeless Dialog Boxes” on 
page 6-73. The TECopy procedure is described in the chapter “TextEdit” in Inside 
Macintosh: Text. 





DialogPaste 


When a dialog box containing an editable text item is active, use the DialogPaste 
procedure to handle the Paste editing command. The DialogPaste procedure is also 
available as the DlgPaste procedure. 


PROCEDURE DialogPaste (theDialog: DialogPtr); 





theDialog A pointer to a dialog record. 
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The DialogPaste procedure checks whether the dialog box has any editable text 
items and, if so, applies the TextEdit procedure TEPaste to the selected editable text 
item. Your application should test whether a dialog box is the frontmost window 

when handling mouse-down events in the Edit menu and then call this routine when 
appropriate. 


For more information about allowing access to your menus when your application 
displays dialog boxes, see “Adjusting Menus for Modal Dialog Boxes” beginning on 
page 6-68 and “Adjusting Menus for Movable Modal and Modeless Dialog Boxes” on 
page 6-73. The TEPaste procedure is described in the chapter “TextEdit” in Inside 
Macintosh: Text. 





DialogDelete 


DESCRIPTION 


SEE ALSO 
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When a dialog box containing an editable text item is active, use the DialogDelete 
procedure to handle the Clear editing command. The DialogDelete procedure is also 
available as the DlgDelete procedure. 


PROCEDURE DialogDelete (theDialog: DialogPtr); 


theDialog A pointer to a dialog record. 


The DialogDelete procedure checks whether the dialog box has any editable text 
items and, if so, applies the TextEdit procedure TEDelete to the selected text. Your 
application should test whether a dialog box is the frontmost window when handling 
mouse-down events in the Edit menu and then call this routine when appropriate. 


For more information about allowing access to your menus when your application 
displays dialog boxes, see “Adjusting Menus for Modal Dialog Boxes” beginning on 
page 6-68 and “Adjusting Menus for Movable Modal and Modeless Dialog Boxes” on 
page 6-73. The TEDelete procedure is described in the chapter “TextEdit” in Inside 
Macintosh: Text. 
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Handling Events in Dialog Boxes 


Handling events in an alert box is very simple: after you invoke an alert box, the Dialog 
Manager handles most events for you by automatically calling the ModalDialog 
procedure. To handle events in a modal dialog box, your application must explicitly call 
the ModalDialog procedure after displaying the dialog box. In either case, when an 
enabled item is clicked, the Dialog Manager returns the item number. You'll then do 
whatever is appropriate in response to that click. For both alert and modal dialog boxes, 
you should also provide a simple event filter function that allows other windows to 
respond to update events and that allows your alert or dialog box to respond to a few 
key-down events for keys such as Return, Enter, and Esc. 


You can use your normal event-handling code to determine whether an event occurs in a 
modeless or movable modal dialog box, or you can use the IsDialogEvent function to 
learn whether they need to be handled as part of a dialog box. Once you determine that 
an event occurs in a modeless or movable modal dialog box, you can use the 
DialogSelect function to handle key-down events in editable text items automatically, 
to handle update and activate events automatically, and to report the enabled items 
clicked by the user. You then respond as appropriate to clicks in your active items. Or 
you can use Control Manager, TextEdit, and Window Manager routines (such as 
FindWindow, BeginUpdate, EndUpdate, FindControl, TrackControl, and 
TEClick) to handle these events without the aid of the Dialog Manager. 











ModalDialog 


DESCRIPTION 


To handle events when you display a modal dialog box, use the ModalDialog 
procedure. 





PROCEDURE ModalDialog (filterProc: ModalFilterProcPtr; 
VAR itemHit: Integer) ; 











filterProc 
A pointer to an event filter function. 


itemHit A number representing the position of the selected item in the item list 
resource for the active modal dialog box. 


Call the ModalDialog procedure immediately after displaying a modal dialog box. The 
ModalDialog procedure assumes that a modal dialog box is displayed as the current 
port, and ModalDialog repeatedly handles events inside that port until an event 
involving an enabled dialog box item—such as a click in a radio button, for example— 
occurs. If the event is a mouse-down event outside the content region of the dialog box, 
ModalDialog emits the system alert sound and gets the next event. After receiving an 
event involving an enabled item, ModalDialog returns its item number in the itemHit 
parameter. Your application should then do whatever is appropriate in response to an 
event in that item. Your application should continue calling ModalDialog until the user 
selects the OK or Cancel button. 
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For events inside the dialog box, ModalDialog passes the event to the event filter 
function pointed to in the filterProc parameter before handling the event. When the 
event filter returns FALSE, ModalDialog handles the event. If the event filter function 
handles the event, the event filter function returns TRUE, and ModalDialog performs 
no more event handling. 





If you set the £ilterProc parameter to NIL, the standard event filter function is 
executed. The standard event filter function returns TRUE and causes ModalDialog to 
return item number 1, which is the number of the default button, when the user presses 
the Return key or the Enter key. However, your application should provide a simple 
event filter function that 


m retums TRUE and the item number for the default button if the user presses the 
Return or Enter key 





m retums TRUE and the item number for the Cancel button if the user presses the Esc 
key or the Command-period key combination 


m updates your windows in response to update events (this allows background 
applications to receive update events) and return FALSE 


m returns FALSE for all events that your event filter function doesn’t handle 





You can use the same event filter function in most or all of your alert and modal 
dialog boxes. 


You can also use the event filter function specified in the filterProc parameter to test 
for and respond to keyboard equivalents and more complex events—for instance, the 
user dragging the cursor within an application-defined item. 


To handle events, ModalDialog calls the IsDialogEvent function. If the result of 
IsDialogEvent is TRUE, then ModalDialog calls the DialogSelect function to 
handle the event. Unless the event filter function returns TRUE, ModalDialog handles 
the event as follows: 











m In response to an activate or update event for the dialog box, ModalDialog activates 
or updates its window. 


m Ifthe user presses the mouse button while the cursor is in an editable text item, 
ModalDialog responds to the mouse activity as appropriate—that is, either by 
displaying an insertion point or by selecting text. If a key-down event occurs and 
there’s an editable text item, ModalDialog uses TextEdit to handle text entry and 
editing automatically. If the editable text item is enabled, ModalDialog returns its 
item number after it receives either the mouse-down or key-down event. Normally, 
editable text items are disabled, and you use the GetDialogItemText procedure to 
read the information in the items only after the user clicks the OK button. 


m Ifthe user presses the mouse button while the cursor is in a control, ModalDialog 
calls the Control Manager function TrackCont rol. If the user releases the mouse 
button while the cursor is in an enabled control, ModalDialog returns the control’s 
item number. Your application should respond appropriately—for example, by 
performing a command after the user clicks the OK button. 
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m Ifthe user presses the mouse button while the cursor is in any other enabled item in 
the dialog box, ModalDialog returns the item’s number, and your application should 
respond appropriately. Generally, only controls should be enabled. If your application 
creates a control more complex than a button, radio button, or checkbox, your 
application must handle events inside that item with your event filter function. 


m Ifthe user presses the mouse button while the cursor is in a disabled item or in no 
item, or if any other event occurs, ModalDialog does nothing. 


SPECIAL CONSIDERATIONS 


SEE ALSO 


Do not use ModalDialog for movable modal dialog boxes (that is, those created with 
the movableDBoxProc window definition ID) or for modeless dialog boxes (that is, 
those created with the noGrowDocProc window definition ID). If you want the Dialog 
Manager to assist you in handling events for movable modal and modeless dialog boxes, 
use the IsDialogEvent and DialogSelect functions instead. 





The ModalDialog procedure calls the Event Manager function GetNextEvent with a 
mask that excludes disk-inserted events. To receive disk-inserted events, your event filter 
function can call the Event Manager procedure Set SystemEventMask. 


When ModalDialog calls TrackControl, it does not allow you to specify the action 
procedure necessary for anything more complex than a button, radio button, or 
checkbox. If you need a more complex control (for example, one that measures how long 
the user holds down the mouse button or how far the user has moved an indicator), you 
can create your own control, a picture, or an application-defined item that draws a 
control- like object in your dialog box. You must then provide an event filter function 
that appropriately handles events in that item. 


Listing 6-26 on page 6-83 illustrates the use of ModalDialog. “Responding to Events in 
Editable Text Items” beginning on page 6-79 describes how ModalDialog uses TextEdit 
to handle text entry and editing in editable text items. The IsDialogEvent and 
DialogSelect functions (which your application may use instead of ModalDialog 
for modeless and movable modal dialog boxes) are described on page 6-138 and 

page 6-139, respectively. See the description of MyEvent Filter on page 6-145 for 
information about the event filter function your application should specify in the 
filterProc parameter. 





The GetNextEvent and SetSystemEventMask routines are described in the chapter 
“Event Manager” in this book. See that chapter as well for a discussion of disk-inserted 
events. See “Responding to Events in Controls” on page 6-78 for a description of how 
your application should respond to events inside of controls; the TrackCont rol 
function is fully described in the chapter “Control Manager” in this book. Also see that 
chapter for information about creating your own nonstandard controls. TextEdit is 
described in the chapter “TextEdit” of Inside Macintosh: Text. 
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IsDialogEvent 


DESCRIPTION 


6-138 


To determine whether a modeless dialog box or a movable modal dialog box is active 
when an event occurs, you can use the IsDialogEvent function. 


FUNCTION IsDialogEvent (theEvent: EventRecord): Boolean; 


theEvent Anevent record returned by an Event Manager function such as 
WaitNextEvent. 


If any event, including a null event, occurs when your dialog box is active, 
IsDialogEvent returns TRUE; otherwise, it returns FALSE. When IsDialogEvent 
retums FALSE, pass the event to the rest of your event-handling code. When 
IsDialogEvent returns TRUE, pass the event to DialogSelect after testing for the 
events that DialogSelect does not handle. 














A dialog record includes a window record. When you use the GetNewDialog, 
NewDialog, or NewColorDialog function to create a dialog box, the Dialog Manager 
sets the windowKind field in the window record to dialogKind. To determine whether 
the active window is a dialog box, IsDialogEvent checks the windowKind field. 





Before passing the event to DialogSelect, you should perform the following tests 
whenever IsDialogEvent returns TRUE: 





m Check whether the event is a key-down event for the Return, Enter, Esc, or 
Command-period keystrokes. When the user presses the Return or Enter key, your 
application should respond as if the user had clicked the default button; when the 
user presses Esc or Command-period, your application should respond as if the user 
had clicked the Cancel button. Use the Control Manager procedure HiliteControl 
to highlight the applicable button for 8 ticks. 


m At this point, you may also want to check for and respond to any special events that 
you do not wish to pass to DialogSelect or that require special processing before 
you pass them toDialogSelect. You would need to do this, for example, if the 
dialog box needs to respond to disk-inserted events. 


m Check whether the event is an update event for a window other than the dialog box 
and, if it is, update your window. 


m For complex items that you create, such as pictures or application-defined items that 
emulate complex controls, test for and respond to mouse events inside those items as 
appropriate. When DialogSelect calls TrackControl1, it does not allow you to 
specify the action procedure necessary for anything more complex than a button, 
radio button, or checkbox. If you need a more complex control (for example, one that 
measures how long the user holds down the mouse button or how far the user has 
moved an indicator), you can create your own control or a picture or an 
application-defined item that draws a control-like object in your dialog box. You must 
then test for and respond to those events yourself. 
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If your application uses IsDialogEvent to help handle events when you display a 
movable modal dialog box, perform the following additional tests before passing events 
to DialogSelect: 


mu Test for mouse-down events in the title bar of the movable modal dialog box and 
respond by dragging the dialog box accordingly. 


mu Test for and respond to mouse-down events in the Apple menu and, if the movable 
modal dialog box includes editable text items, in the Edit menu. (You should disable 
all other menus when you display a movable modal dialog box.) 


m Play the system alert sound for every other mouse-down event outside the movable 
modal dialog box. 


SPECIAL CONSIDERATIONS 





Both IsDialogEvent and DialogSelect are unreliable when running in versions of 
system software earlier than System 7. You shouldn’t use these routines if you expect 
your application to run in earlier versions of system software. 


SEE ALSO 


The WaitNextEvent function is described in the chapter “Event Manager” in this book. 
See Inside Macintosh: Sound for a description of the SysBeep procedure. The 
FrontWindow function is described in the chapter “Window Manager” in this book. 


DialogSelect 


After determining that an event related to an active modeless dialog box or an active 
movable modal dialog box has occurred, you can use the DialogSelect function to 
handle most of the events inside the dialog box. 





FUNCTION DialogSelect (theEvent: EventRecord; 
VAR theDialog: DialogPtr; 
VAR itemHit: Integer): Boolean; 


theEvent Anevent record returned by an Event Manager function such as 
WaitNextEvent. 


theDialog A pointer to a dialog record for the dialog box where the event occurred. 


itemHit A number corresponding to the position of an item within the item list 
resource of the active dialog box. 


DESCRIPTION 


The DialogSelect function handles most of the events relating to a dialog box. If the 
event is an activate or update event for a dialog box, DialogSelect activates or 
updates it and returns FALSE. If the event involves an enabled item, DialogSelect 
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returns a function result of TRUE. In its itemHit parameter, it returns the item number 
of the item selected by the user. In the parameter theDialog, it returns a pointer to 
the dialog record for the dialog box where the event occurred. In all other cases, the 
DialogSelect function returns FALSE. When DialogSelect returns TRUE, do 
whatever is appropriate as a response to the event involving that item in that particular 
dialog box; when it returns FALSE, do nothing. 











Generally, only controls should be enabled in a dialog box; therefore your application 
should normally respond only when DialogSelect returns TRUE after the user clicks 
an enabled control, such as the OK button. 


The DialogSelect function first obtains a pointer to the window containing the event. 
For update and activate events, the event record contains the window pointer. For other 
types of events, DialogSelect calls the Window Manager function FrontWindow. 
The Dialog Manager then makes this window the current graphics port by calling the 
QuickDraw procedure Set Port. Then DialogSelect prepares to handle the event by 
setting up text information if there are any editable text items in the active dialog box. 


If the event is an update event for a dialog box, DialogSelect calls the Window 
Manager procedure BeginUpdate, the Dialog Manager procedure DrawDialog, 

and then the Window Manager procedure EndUpdate. When an item is a control 
defined in a control ('CNTL') resource, the rectangle added to the update region is the 
rectangle defined in the control resource, not the display rectangle defined in the item 
list resource. 





The DialogSelect function handles the event as follows: 


m Inresponse to an activate or update event for the dialog box, DialogSelect 
activates or updates its window and returns FALSE. 





m Ifa key-down event or an auto-key event occurs and there’s an editable text item 
in the dialog box, DialogSelect uses TextEdit to handle text entry and editing, 
and DialogSelect returns TRUE for a function result. In its itemHit parameter, 
DialogSelect returns the item number. 


m Ifa key-down event or an auto-key event occurs and there’s no editable text item in 
the dialog box, DialogSelect returns FALSE. 


m Ifthe user presses the mouse button while the cursor is in an editable text item, 
DialogSelect responds to the mouse activity as appropriate—that is, either by 
displaying an insertion point or by selecting text. If the editable text item is disabled, 
DialogSelect returns FALSE. If the editable text item is enabled, DialogSelect 
retums TRUE and in its itemHit parameter returns the item number. Normally, 
editable text items are disabled, and you use the GetDialogItemText function to 
read the information in the items only after the OK button is clicked. 








m Ifthe user presses the mouse button while the cursor is in a control, DialogSelect 
calls the Control Manager function TrackCont rol. If the user releases the mouse 
button while the cursor is in an enabled control, DialogSelect returns TRUE fora 
function result and in its itemHit parameter returns the control’s item number. Your 
application should respond appropriately—for example, by performing a command 
after the user clicks the OK button. 
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m Ifthe user presses the mouse button while the cursor is in any other enabled item in 
the dialog box, DialogSelect returns TRUE for a function result and in its itemHit 
parameter returns the item’s number. Generally, only controls should be enabled. If 
your application creates a complex control—such as one that measures how far a dial 
is moved—your application must handle mouse events in that item before passing the 
event to DialogSelect. 





m Ifthe user presses the mouse button while the cursor is in a disabled item, or if it is in 
no item, or if any other event occurs, DialogSelect does nothing. 


m If the event isn’t one that DialogSelect specifically checks for (if it’s a null event, 
for example), and if there’s an editable text item in the dialog box, DialogSelect 
calls the TextEdit procedure TEIdle to make the insertion point blink. 





SPECIAL CONSIDERATIONS 


SEE ALSO 


Because DialogSelect handles only mouse-down events in a dialog box and 

key-down events in a dialog box’s editable text items, you should handle other events 

as appropriate before passing them to DialogSelect. Likewise, when DialogSelect 
calls TrackCont rol, it does not allow you to specify any action procedure necessary for 
anything more complex than a button, radio button, or checkbox. If you need a more 
complex control (for example, one that measures how long the user holds down the 
mouse button or how far the user has moved an indicator), you can create your own 
control or a picture or an application-defined item that draws a control-like object in 
your dialog box. You must then test for and respond to those events yourself. 


Within dialog boxes, use the procedures DialogCut, DialogCopy, DialogPaste, and 
DialogDelete to support Cut, Copy, Paste, and Clear commands in editable text boxes. 


The DialogSelect function is unreliable when running in versions of system software 
earlier than System 7. You shouldn’t use this routine if you expect your application to 
run under earlier versions of system software. 


Listing 6-25 on page 6-79 illustrates the use of DialogSelect to make the cursor blink 
in editable text items during null events; Listing 6-29 on page 6-92 illustrates the use of 
DialogSelect to handle mouse events in a modeless dialog box; Listing 6-33 on 

page 6-96 illustrates the use of DialogSelect to handle key-down events in editable 
text items; Listing 6-34 on page 6-98 illustrates the use of DialogSelect to handle 
activate events in a modeless dialog box. 
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DrawDialog 


DESCRIPTION 


SEE ALSO 


If you don’t use any other Dialog Manager routines for handling events in a dialog box, 
you can use the DrawDialog procedure to draw its entire contents. 


PROCEDURE DrawDialog (theDialog: DialogPtr); 


theDialog A pointer toa dialog record. 


The DrawDialog procedure draws the entire contents of the specified dialog box. The 
DrawDialog procedure draws all dialog items, calls the Control Manager procedure 
DrawControl1s to draw all controls, and calls the TextEdit procedure TEUpdate to 
update all static and editable text items and to draw their display rectangles. The 
DrawDialog procedure also calls the application-defined items’ draw procedures if 
the items’ rectangles are within the update region. 





The DialogSelect, ModalDialog, Alert, StopAlert, NoteAlert, and 
CautionAlert routines use DrawDialog automatically. If you use GetNewDialog 
to create a dialog box but don’t use any of these other Dialog Manager routines when 
handling events in the dialog box, you can use DrawDialog to redraw the contents of 
the dialog box when it’s visible. If the dialog box is invisible, first use the Window 
Manager procedure ShowWindow and then use DrawDialog. 


See the chapters “Window Manager” and “Event Manager” in this book for more 
information on update and activate events for windows. The DrawCont rols procedure 
is described in the chapter “Control Manager” in this book. The TEUpdate procedure is 
described in the chapter “TextEdit” in Inside Macintosh: Text. 


UpdateDialog 
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You can use the Updat eDialog procedure to redraw the update region of a 
specified dialog box. The UpdateDialog procedure is also available as the 
UpdtDialog procedure. 


PROCEDURE UpdateDialog (theDialog: DialogPtr; 
updateRgn: RgnHandle) ; 


theDialog A pointer toa dialog record. 
updateRgn A handle to the window region that needs to be updated. 
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The UpdateDialog procedure redraws only the region in a dialog box specified in the 
updateRgn parameter. Because the DialogSelect,ModalDialog, Alert, 
StopAlert, NoteAlert,and CautionAlert routines automatically call DrawDialog 
to handle update events in your alert and dialog boxes, your application might never 
need to use UpdateDialog. 


Instead of drawing the entire contents of the specified dialog box, UpdateDialog 
draws only the items in the specified update region. You can use UpdateDialog in 
response to an update event, and you should usually bracket it by calls to the Window 
Manager procedures BeginUpdate and EndUpdate. The Updat eDialog procedure 
uses the QuickDraw procedure Set Port to make the dialog box the current graphics 
port. For drawing controls, Updat eDialog uses the Control Manager procedure 
UpdateControls, which is faster than the DrawControls procedure. 





Listing 6-35 on page 6-99 illustrates the use of UpdateDialog to respond to update 
events in a modeless dialog box. See the chapter “Window Manager” in this book for 
more information on update and activate events for windows. The UpdateControls 
procedure is described in the chapter “Control Manager” in this book. 


Application-Defined Routines 


MylItem 


If you supply an application-defined item in a dialog box, you must provide a draw 
procedure for the Dialog Manager to use when displaying the item; that procedure is 
referred to in this section as MyIt em. If you want the Dialog Manager to play sounds 
other than the system alert sound, you must provide your own sound procedure, 
referred to in this section as MyAlert Sound. To supplement the Dialog Manager’s 
ability to handle events in the Macintosh multitasking environment, you should provide 
an event filter function that the Dialog Manager calls whenever it displays alert boxes 
and modal dialog boxes. This function is referred to as MyEventFilter. 


To draw your own application-defined item in a dialog box, provide a draw procedure 
that takes two parameters: a window pointer to the dialog box and an item number from 
the dialog box’s item list resource. For example, this is how you should declare the 
procedure if you were to name it MyItem: 


PROCEDURE MyItem (theWindow: WindowPtr; itemNo: Integer); 
theWindow A pointer to the dialog record for the dialog box containing an 
application-defined item. If your procedure can draw in more than 


one dialog box, this parameter tells your procedure which one to 
draw in. 
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itemNo A number corresponding to the position of an item in the item list 
resource for the specified dialog box. If your procedure draws more 
than one item, this parameter tells your procedure which one to draw. 


The Dialog Manager calls your procedure to draw an application-defined item at the 
time you display the specified dialog box. When calling your draw procedure, the Dialog 
Manager sets the current port to the dialog box’s graphics port. Normally, you create an 
invisible dialog box and then use the Window Manager procedure ShowWindow to 
display the dialog box. 


Before you display the dialog box, use the SetDialogItem procedure to install this 
procedure in the dialog record. Before using SetDialogItem, you must first use the 
GetDialogItem procedure to obtain a handle to an item of type userItem. 


If you enable the application-defined item that you draw with this procedure, the 
ModalDialog procedure and the DialogSelect function return the item’s number 
when the user clicks that item. If your application needs to respond to a user action more 
complex than this (for example, if your application needs to measure how long the user 
holds down the mouse or how far the user drags the cursor), your application must track 
the cursor itself. If you use ModalDialog, your event filter function must handle events 
inside the item; if you use DialogSelect, your application must handle events inside 
the item before handing events to DialogSelect. 


Listing 6-17 on page 6-59 illustrates a procedure that draws a bold outline around 

a button of any size and shape; Listing 6-16 on page 6-58 shows the use of 
GetDialogItemand SetDialogItem to install this draw procedure in a dialog 
record. The ShowWindow procedure is described in the chapter “Window Manager” 
in this book. 


MyAlertSound 
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If you want the Dialog Manager to play sounds other than the system alert sound, write 
your own sound procedure and call the ErrorSound procedure to make it the current 
sound procedure. For example, you can declare a sound procedure named 
MyAlertSound, as shown here: 


PROCEDURE MyAlertSound (soundNo: Integer); 


soundNo An integer from 0 to 3, representing the four possible alert stages. 
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For each of the four alert stages that can be reported in the soundNo parameter, your 
procedure can emit any sound that you define. When the Dialog Manager calls your 
procedure, it passes 0 as the sound number for alert sounds specified by the silent 
constant in the alert resource. The Dialog Manager passes 1 for sounds specified by the 
sound1 constant, 2 for sounds specified by the sound2 constant, and 3 for sounds 
specified by the sound3 constant. 


SPECIAL CONSIDERATIONS 


When the Dialog Manager detects a click outside an alert box or a modal dialog box, it 
uses the Sound Manager procedure SysBeep to play the system alert sound. By 
changing settings in the Sound control panel, the user can select which sound to play as 
the system alert sound. For consistency with system software and other Macintosh 
applications, your sound procedure should call SysBeep whenever your sound 
procedure receives sound number 1 (which you can represent with the sound1 constant). 





SEE ALSO 
Listing 6-3 on page 6-22 illustrates how to use MyAlert Sound. The SysBeep procedure 
is described in Inside Macintosh: Sound. 

MyEventFilter 


To supplement the Dialog Manager’s ability to handle events, your application should 
provide an event filter function that the Dialog Manager calls when it displays alert 
boxes and modal dialog boxes. Your event filter function should have three parameters 
and return a Boolean value. For example, this is how you would declare it if you were to 
name it MyEventFilter 





FUNCTION MyEventFilter (theDialog: DialogPtr; 
VAR theEvent: EventRecord; 
VAR itemHit: Integer): Boolean; 





theDialog A pointer to a dialog record for an alert box or a modal dialog box. 





theEvent Anevent record returned by an Event Manager function such as 
WaitNextEvent. 





itemHit A number corresponding to the position of an item in the item list 
resource for the alert or modal dialog box. 
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After receiving an event that it does not handle, your function should return FALSE. 
When your function returns FALSE, ModalDialog handles the event, which you pass 
in the parameter theEvent. (Your function can also change the event to simulate a 
different event and return FALSE, which passes the event to the Dialog Manager for 
handling.) If your function does handle the event, your function should return TRUE 
as a function result, and in the itemHit parameter return the number of the item 
that it handled. The ModalDialog procedure and, in turn, the Alert, NoteAlert, 
StopAlert, and CautionAlert functions then return this item number in their own 
itemHit parameters. 








Your event filter function should perform the following tasks: 


m retum TRUE and the item number for the default button if the user presses Return 
or Enter 





m retum TRUE and the item number for the Cancel button if the user presses Esc or 
Command-period 


m update your windows in response to update events (this allows background 
applications to receive update events) and return FALSE 


m return FALSE for all events that your event filter function doesn’t handle 





You can also use the event filter function to test for and respond to keyboard equivalents 
and more complex events—for instance, the user dragging the cursor in an application- 
defined item. For example, if you provide an application-defined item that requires you 
to measure how long the user holds down the mouse button or how far the user drags 
the cursor, use the event filter function to handle events inside that item. 


The ModalDialog procedure calls the Event Manager function GetNextEvent witha 
mask that excludes disk-inserted events; to receive disk-inserted events, your event filter 
function can call the Event Manager procedure Set SystemEventMask. 


You can use the same event filter function in most or all of your alert and modal 
dialog boxes. 


For alert and modal dialog boxes, the Dialog Manager provides a standard event filter 
function that checks whether the user has pressed the Enter or Return key and, if so, 
returns the item number of the default button. Your event filter function should always 
check whether the Return key or Enter key was pressed and, if so, return the number of 
the default button in the itemHit parameter and a function result of TRUE. 





In all alert and dialog boxes, any buttons that are activated by key sequences should 
invert to indicate which item has been selected. Use the Control Manager procedure 
HiliteControl1 to invert a button for 8 ticks, long enough to be noticeable but not so 
long as to be annoying. The Control Manager performs this action whenever users click 
a button, and your application should do this whenever the user presses the keyboard 
equivalent of a button click. 
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For modal dialog boxes that contain editable text items, your application should handle 
menu bar access to allow use of your Edit menu and its Cut, Copy, Paste, Clear, and 
Undo commands. Your event filter function should then test for and handle clicks 

in your Edit menu and keyboard equivalents for the appropriate commands in your 
Edit menu. Your application should respond by using the procedures DialogCut, 
DialogCopy, DialogPaste, and DialogDelete to support the Cut, Copy, Paste, and 
Clear commands. 


For an alert box, you specify a pointer to your event filter function in a parameter that 
you pass to the Alert, StopAlert, CautionAlert, and NoteAlert functions. For a 
modal dialog box, specify a pointer to your event filter function in a parameter that you 
pass to the ModalDialog procedure. 


Listing 6-27 on page 6-88 illustrates an event filter function. The functions 
GetNextEvent and Set SystemEventMask are described in the chapter 
“Event Manager” in this book. 


This section describes resources used by the Dialog Manager for displaying alerts and 
dialog boxes. These resources are 


m the dialog ('DLOG') resource, which specifies the window type, display rectangle, 
and item list resource for a dialog box 


m the alert ('ALRT') resource, which specifies alert sounds, a display rectangle, and an 
item list resource for an alert box 


m the item list ('DITL') resource, which specifies the items—such as buttons and static 
text—to display in an alert box or a dialog box 


m the dialog color table ('dctb"') resource, which lets you supply a color graphics port 
for a dialog box and also use colors other than the default colors in a dialog box 


m the alert color table ('actb"') resource, which lets you use colors other than the 
default colors in an alert box 


m the item color table ('ictb') resource, which lets you change the default colors, 
typeface, font style, and font size of items in an alert box or a dialog box 


This section describes the structures of these resources after they are compiled by the Rez 
resource compiler, available from APDA. If you are interested in creating the Rez input 
files for these resources, see “Using the Dialog Manager” beginning on page 6-17 for 
detailed information. 
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The Dialog Resource 


You can use a dialog resource to define a dialog box. A dialog resource is a resource of 
type 'DLOG'. All dialog resources must be marked purgeable, and they must have 
resource ID numbers greater than 128. 


To specify the items in a dialog box, you must also provide an item list resource, 
described beginning on page 6-151. Use the Get NewDialog function (described on 
page 6-113) to create the dialog box defined in the dialog resource. 


The format of a Rez input file for a dialog resource differs from its compiled output 
format. This section describes the structure of a Rez-compiled dialog resource. If you 
are concerned only with creating a dialog resource, see “Creating Dialog Boxes” 
beginning on page 6-23. 


Figure 6-42 shows the format of a compiled dialog resource. 


Figure 6-42 Structure of a compiled dialog ('DLOG') resource 
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The compiled version of a dialog resource contains the following elements: 


m Rectangle. This determines the dialog box’s dimensions and, possibly, its position. 
(The last element in the dialog resource usually specifies a position for the dialog box.) 


gm Window definition ID. 





If the integer 0 appears here (as specified in the Rez input file by the dBoxProc 
window definition ID), the Dialog Manager displays a modal dialog box. 
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If the integer 4 appears here (as specified in the Rez input file by the 
noGrowDocProc window definition ID), the Dialog Manager displays a 
modeless dialog box. 


If the integer 5 appears here (as specified in the Rez input file by the 
movableDBoxProc window definition ID), the Dialog Manager displays 
a movable modal dialog box. 


These types of dialog boxes are illustrated in Figure 6-6 on page 6-10, Figure 6-8 on 
page 6-12, and Figure 6-7 on page 6-11, respectively. 


a Visibility. If this is set to a value of 1 (as specified by the visible constant in the Rez 
input file), the Dialog Manager displays this dialog box as soon as you call the 
GetNewDialog function. If this is set to a value of 0 (as specified by the invisible 
constant in the Rez input file), the Dialog Manager does not display this dialog box 
until you call the Window Manager procedure ShowWindow. 


m Close box specification. This specifies whether to draw a close box. Normally, this is 
set to a value of 1 (as specified by the goAway constant in the Rez input file) only for a 
modeless dialog box to specify a close box in its title bar. Otherwise, this is set to a 
value of 0 (as specified by the noGoAway constant in the Rez input file). 


m Reference constant. This contains any value that an application stores here. For 
example, an application can store a number that represents a dialog box type, or 
it can store a handle to a record that maintains state information about the dialog 
box or other window types. An application can use the Window Manager procedure 
SetWRefCon at any time to change this value in the dialog record for a dialog box, 
and you can use the GetWRef£Con function to determine its current value. 


a Item list resource ID. The ID of the item list resource that specifies the items—such as 
buttons and static text—to display in the dialog box. 


a Window title. This is a Pascal string displayed in the dialog box’s title bar only when 
the dialog box is modeless. 


m Alignment byte. This is an extra byte added if necessary to make the previous Pascal 
string end on a word boundary. 


m Dialog box position. This specifies the position of the dialog box on the screen. (If your 
application positions dialog boxes on its own, don’t use these constants, because your 
code may conflict with the Dialog Manager.) 


If 0x0000 appears here (as specified by the noAutoCenter constant in the Rez 
input file), the Dialog Manager positions this dialog box according to the global 
coordinates specified in the rectangle element of this resource. 


If OxBOOA appears here (as specified by the alertPositionParentWindow 
constant in the Rez input file), the Dialog Manager positions the dialog box over 
the frontmost window so that the window’s title bar appears. This is illustrated in 
Figure 6-33 on page 6-63. 

If 0x300A appears here (as specified by the alertPositionMainScreen constant 
in the Rez input file), the Dialog Manager centers the dialog box near the top of the 
main screen. This is illustrated in Figure 6-34 on page 6-63. 

If Ox700A appears here (as specified in the Rez input file by the 
alertPositionParentWindowScreen constant), the Dialog Manager 
positions the dialog box on the screen where the user is currently working. 

This is illustrated in Figure 6-35 on page 6-64. 
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The Alert Resource 
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You can use an alert resource to define an alert. An alert resource is a resource of type 
"ALRT'. All alert resources must be marked purgeable, and they must have resource ID 
numbers greater than 128. 


To specify the items in an alert box, you must also provide an item list resource, 
described beginning on page 6-151. To display the alert, you call either the NoteAlert, 
CautionAlert, StopAlert, orAlert function and pass it the resource ID of the 

alert resource. The NoteAlert, CautionAlert, StopAlert, and Alert functions 

are described in “Creating Alerts” beginning on page 6-105. 


The format of a Rez input file for an alert resource differs from its compiled output 
format. This section describes the structure of a Rez-compiled alert resource. If you are 
concerned only with creating an alert resource, see “Creating Alert Sounds and Alert 
Boxes” beginning on page 6-18. 


Figure 6-43 shows the structure of a compiled alert resource. 


Figure 6-43 Structure of a compiled alert ('ALRT') resource 
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The compiled version of an alert resource contains the following elements: 


m Rectangle. This determines the alert box’s dimensions and, possibly, its position. (The 
last element in the alert resource usually specifies a position for the alert box.) 


a Item list resource ID. The ID of the item list resource that specifies the items—such as 
buttons and static text—to display in the alert box. 


a Fourth-stage alert information. This specifies the response when the user repeats the 
action that invokes this alert four or more consecutive times. The Dialog Manager 
responds in the manner specified in the 4 bits that make up this element. 


If the first bit is set, the Dialog Manager draws a bold outline around the second 
item in the item list resource (typically, the Cancel button) and—if your application 
does not specify an event filter function—returns 2 when the user presses the 
Return or Enter key at the fourth consecutive occurrence of the alert. If the first bit 
is not set, the Dialog Manager draws a bold outline around the first item in the item 
list resource (typically, the OK button) and—if your application does not specify an 
event filter function—returns 1 when the user presses the Return or Enter key. 
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If the second bit is set, the Dialog Manager displays the alert box at this stage. If the 
second bit is not set, the Dialog Manager doesn’t display the alert box at this stage. 


If neither of the next 2 bits is set, the Dialog Manager plays no alert sound at this 
stage. If bit 3 is set and bit 4 is not set, the Dialog Manager plays the first alert 
sound—by default, the system alert sound. If bit 3 is not set and bit 4 is set, the 
Dialog Manager plays the second alert sound; by default, it plays the system alert 
sound twice. If both bit 3 and bit 4 are set, the Dialog Manager plays the third alert 
sound; by default, it plays the system alert sound three times. By defining your 
own alert sound (described on page 6-144) and calling the ErrorSound procedure 
(described on page 6-104) to make it the current sound procedure, you can specify 
your own alert sounds. 





m Third-stage alert information. This specifies the response when the user repeats the 
action that invokes this alert three consecutive times. The Dialog Manager interprets 
these 4 bits in the manner described for the fourth-stage alert. 


m Second-stage alert information. This specifies the response when the user repeats the 
action that invokes this alert two consecutive times. The Dialog Manager interprets 
these 4 bits in the manner described for the fourth-stage alert. 


m First-stage alert information. This specifies the response for the first time that the user 
performs the action that invokes this alert. The Dialog Manager interprets these 4 bits 
in the manner described for the fourth-stage alert. 


m Alert box position. This specifies the position of the alert box on the screen. (If your 
application positions alert boxes on its own, don’t use these constants, because your 
code may conflict with the Dialog Manager.) 

If 0x0000 appears here (as specified by the noAutoCenter constant in the Rez 
input file), the Dialog Manager positions this alert box according to the global 
coordinates specified in the rectangle element of this resource. 

If OxBOOA appears here (as specified by the alertPositionParentWindow 
constant in the Rez input file), the Dialog Manager positions the alert box over the 
frontmost window so that the window’s title bar appears. This is illustrated in 
Figure 6-33 on page 6-63. 

If 0x300A appears here (as specified by the alert PositionMainScreen constant 
in the Rez input file), the Dialog Manager centers the alert box near the top of the 
main screen. This is illustrated in Figure 6-34 on page 6-63. 

If Ox700A appears here (as specified in the Rez input file by the 
alertPositionParentWindowScreen constant), the Dialog Manager 
positions the alert box on the screen where the user is currently working. 

This is illustrated in Figure 6-35 on page 6-64. 


The Item List Resource 


You use an item list resource to specify items—such as buttons and text—in alert boxes 
and dialog boxes. An item list resource is a resource with the resource type 'DITL'. All 
item list resources must be marked purgeable, and they must have resource ID numbers 
greater than 128. 
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For an alert box, you specify the resource ID of the item list resource in an alert 

resource (described beginning on page 6-150). For a dialog box that you create with 

the GetNewDialog function, you specify the resource ID of the item list resource ina 
dialog resource (described beginning on page 6-148). For a dialog box that you create 
with either the NewColorDialog function (described on page 6-115) or the NewDialog 
function (described on page 6-118), you use the Resource Manager function 
GetResource to read the item list resource into memory and to provide a handle to 

the item list resource in memory. 


The format of a Rez input file for an item list resource differs from its compiled output 
format. This section describes the structure of a Rez-compiled item list resource. If you 
are concerned only with creating an item list resource, see “Providing Items for Alert and 
Dialog Boxes” beginning on page 6-26. 


Figure 6-44 shows the format of a compiled item list resource. 


Figure 6-44 Structure of a compiled item list ('DITL') resource 
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The compiled version of an item list resource contains the following elements: 


gm Item count minus 1. This value is 1 less than the total number of items defined in 
this resource. 


mg A variable number of items. 


The format of each item depends on its type. Figure 6-45 shows the format of an item 
defined to be a button, a checkbox, a radio button, a static text item, or an editable 
text item. 

The compiled version of a button, checkbox, radio button, static text item, or editable 
text item consists of the following elements: 


m Reserved. The Dialog Manager uses the element for storage. 


m Display rectangle. This determines the size and location of the item in the alert box or 
dialog box. The display rectangle is specified in coordinates local to the alert box 
or dialog box; these coordinates specify the upper-left and lower-right corners of 
the item. 
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Figure 6-45 Structure of compiled button, checkbox, radio button, static text, and editable 
text items 
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m Enable flag. This specifies whether the item is enabled or disabled. If this bit is set, 
the item is enabled and the Dialog Manager reports to your application whenever 
mouse-down events occur inside this item. 


m Item type. 





If this bit string is set to 4 (as specified in the Rez input file by the Button 
constant), then the item is a button. 

If this bit string is set to 5 (as specified in the Rez input file by the CheckBox 
constant), then the item is a checkbox. 





If this bit string is set to 6 (as specified in the Rez input file by the RadioButton 
constant), then the item is a radio button. 

If this bit string is set to 8 (as specified in the Rez input file by the StaticText 
constant), then the item is static text. 





If this bit string is set to 16 (as specified in the Rez input file by the Edit Text 
constant), then the item is editable text. 


m Text. This specifies the text that appears in the item. This element consists of a length 
byte and as many as 255 additional bytes for the text. (“Titles for Buttons, Checkboxes, 
and Radio Buttons” beginning on page 6-37 and “Text Strings for Static Text and 
Editable Text Items” beginning on page 6-40 contain recommendations about appro- 
priate text in items.) 


For a button, checkbox, or radio button, this is the title for that control. 
For a static text item, this is the text of the item. 


For an editable text item, this can be an empty string (in which case the editable 
text item contains no text), or it can be a string that appears as the default string in 
the editable text item. 


a Alignment byte. This is added if necessary to make the previous text string end ona 
word boundary. 
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Figure 6-46 shows the format for an element defined to be a control, an icon, or a 
picture item. 


Figure 6-46 Structure of compiled control, icon, and picture items 
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The compiled version of a control, an icon, or a picture item consists of the following 
elements: 


m Reserved. The Dialog Manager uses the element for storage. 


m Display rectangle. This determines the size and location of the item in the alert box 
or dialog box. The display rectangle is specified in coordinates local to the alert or 
dialog box. 


m Enable flag. This specifies whether the item is enabled or disabled. If this bit is set, the 
item is enabled and the Dialog Manager reports to your application whenever 
mouse-down events occur inside this item. 

m Item type. 


If this 7-bit string is set to 7 (as specified in the Rez input file by the Control 
constant), then the item is a button. 


If this is set to 32 (as specified in the Rez input file by the Icon constant), then the 
item is an icon. 


If this is set to 64 (as specified in the Rez input file by the Picture constant), then 
the item is a QuickDraw picture. 

m Resource ID. 
For a control item, this is the resource ID of a 'CTRL' resource. 


For an icon item, this is the resource ID of an 'ICON' resource and, optionally, a 
"cicn' resource 


For a picture item, this is the resource ID of a 'PICT' resource. 


Figure 6-47 shows the format for an application-defined item. 
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Figure 6-47 Structure of a compiled application-defined item 
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The compiled version of an application-defined item consists of the following elements: 
m Reserved. The Dialog Manager uses the element for storage. 


m Display rectangle. This determines the size and location of the application-defined 
item in the alert box or dialog box. The display rectangle is specified in coordinates 
local to the alert box or dialog box. 


m Enable flag. This specifies whether the application-defined item is enabled or 
disabled. If this bit is set, the item is enabled and the Dialog Manager reports to 
your application whenever mouse-down events occur inside this item. 


m Item type. This is set to a value of 0 (as specified in the Rez input file by the 
UserItem constant). 


Figure 6-48 shows the format for a help item. (Help items are described in detail in the 
chapter “Help Manager” of Inside Macintosh: More Macintosh Toolbox.) 


Figure 6-48 Structure of compiled help items 
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The compiled version of a help item consists of the following elements: 


Reserved. The Dialog Manager uses the element for storage. 
Reserved. This should be set to 0. 


Enable flag. This specifies whether the item is enabled or disabled. For help items, this 
bit should never be set, because the Dialog Manager cannot report to your application 
when mouse-down events occur inside the item. 


Item type. This is set to 1 (as specified in the Rez input file by the HelpItem constant). 


Size. This specifies the number of bytes contained in the rest of this element. This is set 
to 4 for an item identified by either the HMScanhdlgorHMScanhrct identifier, or it’s 
set to 6 for an item identified by the HMScanAppendhd1g identifier. 


HelpItem type. This specifies the type of help item defined in the resource. 
For an item identified by the HMScanhd1g identifier, this element contains the 
value 1. 
For an item identified by the HMScanhrct identifier, this element contains the 
value 2. 
For an item identified by the HMScanAppendhdlg identifier, this element contains 
the value 8. 


Resource ID. This is the resource ID of the resource containing the help messages for 
this alert box or dialog box. 
For an item identified by either the HMScanhdlg or HMScanAppendhdlg 
identifier, this is the ID of an 'hdlg' resource. 
For an item identified by the HMScanhrct identifier, this is the ID of an 
"hret ' resource. 


Item number. This is available only for an item identified by the HMScanAppendhdlg 
identifier. This is the item number within the alert box or dialog box after which the 
help messages specified in the 'hdlg' resource should be displayed. These help 
messages relate to the items that are appended to the alert box or dialog box. (The 
item list resource does not contain these 2 bytes for items identified by either the 
HMScanhdlg or HMScanhrct identifier.) 
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On color monitors, the Dialog Manager automatically adds color to your alert and dialog 
boxes so that they match the colors of the windows, alert boxes, and dialog boxes used 
by system software. These colors provide aesthetic consistency across all monitors, from 
black-and-white displays to 8-bit color displays. On a color monitor, for example, the 
racing stripes in the title bar of a modeless dialog box are gray, the close box and 
window frame are in color, and the buttons and text are black. 


When you create dialog resources, your application’s dialog boxes use the system’s 
default colors. Typically, this is all you need to do to provide color for your dialog 
boxes—with the following exceptions: 


When you need to include a color version of an icon in a dialog box, you must create a 
resource of type 'cicn' with the same resource ID as the black-and-white 'ICON' 
resource specified in the item list resource. Plate 2 at the front of this book shows an 
alert box that includes a color icon. 
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m When you need to produce a blended gray color for outlining the inactive (that is, 
dimmed) default button, you must create a dialog color table ('dctb') resource with 
the same resource ID as the dialog resource. 


“Using an Application-Defined Item to Draw the Bold Outline for a Default Button” 
beginning on page 6-56 explains how to create a draw routine that outlines the default 
button of a dialog box. If you deactivate a dialog box, you should dim its buttons and 
use gray to draw the outline for the default button. Because GetNewDialog and 
NewDialog supply black-and-white graphics ports for dialog boxes, you can create a 
dialog color table resource for the dialog box to force the Dialog Manager to supply a 
color graphics port. Then you can use a blended gray color for the outline for the default 
button. (The NewColorDialog function supplies a color graphics port.) 


Even when you create a dialog color table resource for drawing a gray outline, you 
should not change the system’s default colors. If you feel absolutely compelled to use 
nonstandard colors, you can use the Dialog Manager to specify colors other than the 
default colors. Your application can specify its own colors for a dialog box by creating a 
dialog color table ('dctb"') resource with the same resource ID as the dialog resource 
(described beginning on page 6-148). You don’t have to call any new routines to change 
the colors used in dialog boxes. When you call the GetNewDialog function, for 
example, the Dialog Manager automatically attempts to load a dialog color table 
resource with the same resource ID as the dialog resource. 


Be aware, however, that nonstandard colors in your dialog boxes may initially confuse 
your users. Also be aware that despite any changes you may make, users can alter the 
colors of dialog boxes anyway by changing settings in the Color control panel. 


A WARNING 
Because the behavior of color alert and dialog boxes, color items, and 
color icons is unreliable on computers using system software versions 
earlier than System 7, do not create these color elements if you wish to 
maintain backward compatibility. a 
A dialog color table resource has exactly the same format as a window color table (that 
is, a resource of type 'wctb'), which is described in the chapter “Window Manager” of 
this book. 


If the dialog box’s content color isn’t white, specify the invisible constant in the 
dialog resource. Use the Window Manager procedure ShowWindow to display the dialog 
box when it’s the frontmost window. If the dialog box is a modeless dialog box that is 
not in front, use the Window Manager procedure ShowHide to display it. 


The Alert Color Table Resource 


On color monitors, the Dialog Manager automatically adds color to your alert boxes so 
that they match the colors of the windows and alerts used by system software. When 
you create alert resources, your application’s alert boxes use the system’s default colors. 
Typically, this is all you need to do to provide color for your alert boxes. (However, to 
include a color version of an icon in an alert box, you must add a resource of type 

‘cicn' with the same resource ID as the black-and-white 'ICON' resource specified in 
the item list resource.) 
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If you feel absolutely compelled to use nonstandard colors, you can use the Dialog 
Manager to specify colors other than the default colors. Your application can specify its 
own colors for an alert box by creating an alert color table ('actb") resource with the 
same resource ID as the alert resource (described beginning on page 6-150). You don’t 
have to call any new routines to change the colors used in alert or dialog boxes. When 
you call the Alert function, for example, the Dialog Manager automatically attempts to 
load an alert color table resource with the same resource ID as the alert resource. 


Be aware, however, that nonstandard colors in your alert boxes may initially confuse 
your users. Also be aware that despite any changes you may make, users can alter the 
colors of dialog boxes anyway by changing settings in the Color control panel. 


WARNING 

Because the behavior of color alert and dialog boxes, color items, and 

color icons is unreliable on computers using system software versions 

earlier than System 7, do not create these color elements if you wish to 

maintain backward compatibility. a 

An alert color table resource has exactly the same format as a window color table 
('wctb") resource, which is described in the chapter “Window Manager” of this book. 


The Item Color Table Resource 
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On color monitors, the Dialog Manager automatically draws the items in your dialog 
and alert boxes so that they match the colors of the items used by system software in its 
dialog and alert boxes. The Dialog Manager also uses the default system font when it 
draws the text in the static text and editable text items of your dialog and alert boxes. 


If you feel absolutely compelled to use nonstandard fonts and colors, you can use the 
Dialog Manager to specify your own colors, typeface, font style, and font size. 


Note 

The Dialog Manager displays the typeface, font style, and font size you 

specify only on color monitors. 

Your application can specify these by creating an item color table ('ictb') resource 
with the same resource ID as the dialog or alert box’s item list resource , and then 
providing a dialog color table resource for a dialog box or an alert color table resource 
for an alert box. You don’t have to call any new routines to change the colors, typefaces, 
font styles, or font sizes used in dialog boxes. When you call the GetNewDialog 
function, for example, the Dialog Manager automatically attempts to load an item color 
table resource with the same resource ID as the item list resource. 


Note 

To make it easier to localize your application for other script 

systems, you should not change the font. Do not use a smaller font, 

such as 9-point Geneva; some script systems, such as KanjiTalk, 

require 12-point fonts. 

Also, be aware that nonstandard colors for items in your dialog and alert boxes may 
initially confuse your users. 
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WARNING 

Because the behavior of color alert and dialog boxes, color items, and 
color icons is unreliable on computers using system software versions 
earlier than System 7, do not create these color elements if you wish to 
maintain backward compatibility. a 


If you want to provide an item color table resource for an alert box or a dialog box, you 
must create an alert color table resource or a dialog color table resource, even if the item 
color table resource has no actual color information and describes only static text and 
editable text style changes. 


An item color table resource is a resource of type 'ictb'. All item color table resources 
must have resource ID numbers greater than 128. 


There is no Rez template available for creating item color table resources. When 
you compile an item color table resource, it should follow the format illustrated in 
Figure 6-49. 


Figure 6-49 Structure of a compiled item color table resource 
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You define an item color table resource for a dialog box or an alert box by specifying 
these elements in a resource with the 'ictb"' resource type: 


m Items. These consist of a variable number of items, corresponding to those in an item 
list resource with the same resource ID as this item color table resource. 
= Control color tables and text style tables. 


A control color table defines the colors used in a control. Several controls can share 
the same control color table. 


A text style table defines the font family, font style, font size, and color of text in an 
editable text item or a static text item. Several editable text and static text items can 
share the same text style table. 


m Optionally, a list of font families. If you use any text style tables, you generally 
conclude the item color table resource with a list of text strings, each of which 
specifies a font family. Although you may specify font numbers instead of font names, 
it’s much more reliable to specify names, because system software may renumber 
these fonts as they are installed and removed. For every editable text item and static 
text item listed at the top of the item color table resource, specify a font family at the 
bottom of the resource. 


The information contained in an element depends on the type of item it describes: 
a Item data. This contains information about how this item is described in the rest of 
this resource. 
For a control, this is the length (in bytes) of its control color table. 


For a Static text item or an editable text item, the bits of this element determine 
which elements of the text style table to use and are interpreted as follows: 


Bit Meaning 

Change the font family. 

Change the typeface. 

Change the font size. 

Change the font foreground color. 
Add the font size. 

13. Change the font background color. 
14 ~— Change the font mode. 


PrP won KF © 


15 The font element is an offset to the name. 


a Item offset. The number of bytes from the beginning of the resource to either the 
control color table or the text style table that describes this item. 


When both the item data and item offset elements are set to 0, then the control or text 
item is drawn with the default colors, typeface, font size, and font style. Even if only the 
first few items of the dialog box have color style information, there must be room for all 
of the items actually in the box (with the item data and item offset elements of the 
unused entries set to 0). 
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For controls, the colors are described by a color table identical to a 'cctb' resource used 
by the Control Manager. Multiple controls can use the same color table. If the resource 
sets both the item data and the item offset element to 0, then the system’s default colors 
are used for the control. The format of a control color table is illustrated in Figure 6-50. 


Figure 6-50 Structure of a compiled control color table 
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A control color table consists of the following elements: 
m Reserved. This should always be set to a value of 0. 
m Reserved. Again, should always be set to a value of 0. 


a Number of control parts. For standard controls other than scroll bars, this should be 
set to 3, because a standard control uses only three parts: frame, control body, and 
text. For scroll bars, this should be set to 12; see the description of the control color 
table resource in the chapter “Control Manager” for information on specifying the 
colors for a scroll bar. To create a control that uses other parts, you must create a 
custom 'CDEF'' resource, as described in the chapter “Control Manager” in this book. 
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Part identifier. This is a value that identifies a part of the first control. The following 
list shows the values and constants they represent for the standard controls other than 
scroll bars. For information on the part identifiers for a scroll bar, see the description 
of the control color table resource in the chapter “The Control Manager” in this book. 
They can be listed in any order in the control color table. 





Constant Value Control part 
cFrameColor 0 Frame 
cBodyColor 1 Body 
cTextColor Z Text (such as titles) 


Red component. This is an integer that represents the intensity of the red component 
of the color to use when drawing this control part. 


Green component. This is an integer that represents the intensity of the green 
component of the color to use when drawing this control part. 


Blue component. This is an integer that represents the intensity of the blue component 
of the color to use when drawing this control part. 


Part identifier, and the red, green, and blue color components for the next control part. 
Specify color components for every part of this control whose color you want to 
change. If a part is not listed in the control color table, the Dialog Manager draws it in 
its default color. 


Figure 6-51 shows the format of a text style table. 


Figure 6-51 Structure of a compiled text style table 


Red component ior text 
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The text style table must be 20 bytes long, as shown in Figure 6-51. Multiple editable text 
and static text items can use the same text style record. To display text in the standard 
typeface, color, font size, and font style, set the item data and item offset elements for the 
item to 0. Allocate space for all fields in the text style table, even if they are not used. 


A text style table consists of the following elements (see Inside Macintosh: Text for a 
discussion of font families, font style, and point sizes): 


Typeface. This is the name of the font family to use. If bit 15 in the item data element is 
set to 1, then this element contains an offset (in bytes) to a font name element at the 
end of the resource. If bit 0 in the item data element is set to 1, then this element 
contains the number of a font family. If bit 0 in the item data element is set to 0, this 
element is set to 0, and the system default font is used. 


Font style. This is the font style to use. If bit 1 in the item data element is set to 1, then 
this element uses the bits of the low-order byte to describe which styles to apply to the 
text. If all bits in the low-order byte are set to 0, the plain font style is used. The bit 
numbers and the styles they represent are 


Bit 

value Style 

0 Bold 

1 Italic 

2 Underline 
3 Outline 

4 Shadow 

5 Condensed 
6 Extended 


Font size. This is the point size of the font. If bit 2 in the item data element is set to 1, 
this element contains a value representing a point size. If bit 4 in the item data element 
is set to 1, this element contains a value to add to the current point size of the text. If 
bit 0 in the item data element is set to 0, this element is set to 0, and the system font 
size (12) is used. 


Text red color. If bit 3 in the item data element is set to 1, this element contains an 
integer that represents the intensity of the red component of the color to use when 
drawing the text. 


Text green color. If bit 3 in the item data element is set to 1, this element contains an 
integer that represents the intensity of the green component of the color to use when 
drawing the text. 


Text blue color. If bit 3 in the item data element is set to 1, this element contains an 
integer that represents the intensity of the blue component of the color to use when 
drawing the text. 


Background red color. If bit 13 in the item data element is set to 1, this element 
contains an integer that represents the intensity of the red component of the color 
to use when drawing the background behind the text. 


Dialog Manager Reference 6-163 


CHAPTER 6 


Dialog Manager 


m Background green color. If bit 13 in the item data element is set to 1, this element 
contains an integer that represents the intensity of the green component of the color 
to use when drawing the background behind the text. 


m Background blue color. If bit 13 in the item data element is set to 1, this element 
contains an integer that represents the intensity of the blue component of the color 
to use when drawing the background behind the text. 


mu Mode. If bit 14 in the item data element is set to 1, this element contains an integer 
that represents how characters are placed in the bit image. The values that the Dialog 
Manager interprets and the constants that represent them are listed here. See Inside 
Macintosh: Imaging for a discussion of source transfer modes. 


Constant Value 
scror 1 
srcXor 2 
srcBic 3 
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Summary of the Dialog Manager 


Pascal Summary 








Constants 

CONST 

{checking for AppendDITL, ShortenDITL, CountDITL using Gestalt function} 
gestaltDITLExtAttr = 'ditl'; {Gestalt selector for AppendDITL, etc.} 
gestaltDITLExtPresent = 0; {if this bit's set, then AppendDITL, } 


{ ShortenDITL, & CountDITL are available} 


{item types for GetDialogItem, SetDialogItem} 


ctrlitem = 4; {add this constant to the next four constants} 
btnCtrl = 0; {standard button control} 

chkCtrl = 1; {standard checkbox control} 

radctrl = 2; {standard radio button} 

resCtrl = 3; {control defined in a control resource} 
helpiItem = 1; {help balloons} 

statText = 8; {static text} 

editText = 16; {editable text} 

iconItem = 32; {icon} 

picItem = 64; {QuickDraw picture} 

userItem = 0; {application-defined item} 

itemDisable = 128; {add to any of the above to disable it} 


{item numbers 


ok 
cancel 


{resource IDs 


stopiIcon 
notelIcon 


of OK and Cancel buttons in alert boxes} 
ans {first button is OK button} 
2} {second button is Cancel button} 


of alert box icons} 


cautionIcon = 2; 


{constants used for theMethod parameter in AppendDITL} 


overlayDITL = 0; {overlay existing items} 
appendDITLRight = 1; {append at right} 
appendDITLBottom = 2; {append at bottom} 
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{constants for procID parameter of NewDialog, NewColorDialog} 


dBoxProc = 1; {modal dialog box} 
noGrowDocProc = 4; {modeless dialog box} 
movableDBoxProc = 5; {movable modal dialog box} 

Data Types 

TYPE DialogPtr = WindowPtr; 

ResumeProcPtr = ProcPtr; 

SoundProcPtr = ProcPtr; 

ModalFilterProcPtr = ProcPtr; 

DialogPeek = “*DialogRecord; 

DialogRecord = 

RECORD 
window: WindowRecord; {dialog window} 
items: Handle; {item list resource} 
textH: TEHandle; {current editable text item} 
editField: Integer; {editable text item number minus 1} 
editOpen: Integer; {used internally} 
aDefItem: Integer; {default button item number} 

END; 


DITLMethod = Integer; 


Dialog Manager Routines 


Initializing the Dialog Manager 














PROCEDURE InitDialogs (resumeProc: ResumeProcPtr) ; 

PROCEDURE ErrorSound (soundProc: SoundProcPtr) ; 

PROCEDURE SetDialogFont (fontNum: Integer); {also spelled SetDAFont } 

Creating Alerts 

{some routines have 2 spellings--see Table 6-1 for the alternate spellings} 

FUNCTION Alert (alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer; 

FUNCTION StopAlert (alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer; 

FUNCTION NoteAlert (alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer; 

FUNCTION CautionAlert (alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer; 

FUNCTION GetAlertStage : Integer; 














PROCEDURE ResetAlertStage; 
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Creating and Disposing of Dialog Boxes 


{some routines have 2 spellings-—-see Table 6-1 for the alternate spellings} 


FUNCTION GetNewDialog 


FUNCTION NewColorDialog 


FUNCTION NewDialog 


PROCEDURE CloseDialog 
PROCEDURE DisposeDialog 


(dialogID: Integer; dStorage: Ptr; 
behind: WindowPtr): 


(dStorage: Ptr; boundsRect: Rect; title: 
Str255; visible: Boolean; procID: Integer; 


DialogPtr; 





behind: WindowPtr; goAwayFlag: Boolean; 
refCon: LongInt; items: Handle): DialogPtr; 
(dStorage: Ptr; boundsRect: Rect; title: 
Str255; visible: Boolean; procID: Integer; 
behind: WindowPtr; goAwayFlag: Boolean; 


refCon: LongInt; items: Handle): DialogPtr; 


(theDialog: DialogPtr); 
(theDialog: DialogPtr); 


Manipulating Items in Alert and Dialog Boxes 


{some routines have 2 spellings—-see Table 6-1 for the alternate spellings} 


PROCEDURE GetDialogItem 


PROCEDURE SetDialogItem 


PROCEDURE HideDialogItem 
PROCEDUR 


Gl 





ShowDialogItem 
FUNCTION FindDialogItem 
PROCEDURE AppendDITL 





PROCEDURE ShortenDITL 
FUNCTION CountDITL 


(theDialog: DialogPtr; itemNo: Integer; 
VAR itemType: Integer; VAR item: Handle; 
VAR box: Rect); 


(theDialog: DialogPtr; itemNo: Integer; 
itemType: Integer; item: Handle; box: Rect); 


(theDialog: DialogPtr; itemNo: Integer) ; 
(theDialog: DialogPtr; itemNo: Integer); 
(theDialog: DialogPtr; thePt: Point): Integer; 


(theDialog: DialogPtr; theDITL: Handle; 
theMethod: DITLMethod) ; 


(theDialog: DialogPtr; numberItems: Integer); 








(theDialog: DialogPtr): Integer; 


Handling Text in Alert and Dialog Boxes 


{some routines have 2 spellings-—-see Table 6-1 for the alternate spellings} 


PROCEDURE ParamText 


PROCEDURE GetDialogItemText 
PROCEDURE SetDialogItemText 


(param0O: Str255; paraml: Str255; 
param2: Str255; param3: Str255); 


(item: Handle; VAR text: Str255); 
(item: Handle; text: Str255); 


PROCEDURE SelectDialogItemText 


PROCEDURE DialogCut 
PROCEDURE DialogCopy 


(theDialog: DialogPtr; itemNo: Integer; 
strtSel: Integer; endSel: Integer); 


(theDialog: DialogPtr); 
(theDialog: DialogPtr); 
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PROCEDURE DialogPaste (theDialog: DialogPtr); 
PROCEDURE DialogDelete (theDialog: DialogPtr); 





Handling Events in Dialog Boxes 





{some routines have 2 spellings—-see Table 6-1 for the alternate spellings} 











PROCEDURE ModalDialog (filterProc: ModalFilterProcPtr; VAR itemHit: 
Integer) ; 

FUNCTION IsDialogEvent (theEvent: EventRecord): Boolean; 

FUNCTION DialogSelect (theEvent: EventRecord; VAR theDialog: 
DialogPtr; VAR itemHit: Integer): Boolean; 

PROCEDURE DrawDialog (theDialog: DialogPtr); 

PROCEDURE UpdateDialog (theDialog: DialogPtr; updateRgn: RgnHandle) ; 





Application-Defined Routines 














PROCEDURE MyItem (theWindow: WindowPtr; itemNo: Integer) ; 
PROCEDURE MyAlertSound (soundNo: Integer); 
FUNCTION MyEventFilter (theDialog: DialogPtr; VAR theEvent: 





EventRecord; VAR itemHit: Integer): Boolean; 


C Summary 


Constants 


enum { 

/*checking for AppendDITL, ShortenDITL, CountDITL using Gestalt function*/ 
#define gestaltDITLExtAttr 'ditl' /*Gestalt selector*/ 
gestaltDITLExtPresent = 0 /*if this bit's set, then AppendDITL, */ 

/* ShortenDITL, & CountDITL are available*/ 





hi 





enum { 
/*item types for GetDItem, SetDItem*/ 
ctrlItem = 4, /*add this constant to the next four constants*/ 
btnCtrl = 0, /*standard button control*/ 
chkCtrl = iL, /*standard checkbox control*/ 
radCtrl = 2, /*standard radio button*/ 
resCtrl = 3, /*control defined in a control resource*/ 
statText = 8, /*static text*/ 
editText = 16, /*editable text*/ 
iconItem = 32, /*icon*/ 
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picItem = 64, /*QuickDraw picture*/ 

userItem = 0, /*application-defined item*/ 

helpItem = 1, /*help balloons*/ 

itemDisable = 128,/*add to any of the above to disable it*/ 


/*item numbers of OK and Cancel buttons in alert boxes*/ 
ok = 1, /*first button is OK button*/ 
cancel = 2, /*second button is Cancel button*/ 


/*resource IDs of alert box icons*/ 


stopiIcon =-0; 
noteIcon = 1, 
cautionIcon = 2 
}; 
enum { 


/*constants used for theMethod parameter in AppendDITL*/ 


overlayDITL = 0, /*overlay existing items*/ 
appendDITLRight = 1, /*append at right*/ 
appendDITLBottom = 2 /*append at bottom*/ 

}; 

enum { 

/*constants for procID parameter of NewDialog, NewColorDialog*/ 
dBoxProc = 1, /*modal dialog box*/ 
noGrowDocProc = 4, /*modeless dialog box*/ 
movableDBoxProc =-5 /*movable modal dialog box*/ 

}; 

Data Types 


typedef WindowPtr DialogPtr; 


typedef struct DialogRecord DialogRecord; 
typedef struct DialogRecord *DialogPeek; 


struct DialogRecord{ 





WindowRecord window; /*dialog window*/ 

Handle items; /*item list resource*/ 

TEHandle textH; /*current editable text item*/ 

short editField; /*editable text item number minus 1*/ 
short editOpen; /*used internally*/ 

short aDefItem; /*default button item number*/ 


}; 
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typedef pascal void (*ResumeProcPtr) (void); 
typedef pascal void (*SoundProcPtr) (void); 





typedef pascal Boolean (*ModalFilterProcPtr) (DialogPtr theDialog, 
EventRecord *theEvent, short *itemHit); 
typedef short DITLMethod; 


Dialog Manager Routines 


Initializing the Dialog Manager 





pascal void InitDialogs (ResumeProcPtr resumeProc) ; 

pascal void ErrorSound (SoundProcPtr soundProc) ; 

pascal void SetDialogFont (short fontNum); /*also spelled SetDAFont*/ 
Creating Alerts 

/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/ 
pascal short Alert (short alertID, ModalFilterProcPtr filterProc); 
pascal short StopAlert (short alertID, ModalFilterProcPtr filterProc) ; 
pascal short NoteAlert (short alertID, ModalFilterProcPtr filterProc); 
pascal short CautionAlert (short alertID, ModalFilterProcPtr filterProc); 
#define GetAlertStage() (* (short*) OxQAQA); 


pascal void ResetAlertStage (void); 


Creating and Disposing of Dialog Boxes 


/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/ 


pascal DialogPtr GetNewDialog 
(short dialogID, void *dStorage, 
WindowPtr behind); 


pascal DialogPtr NewColorDialog 
(void *dStorage, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible, 
short procID, WindowPtr behind, 
Boolean goAwayFlag, long refCon, Handle items); 


pascal DialogPtr NewDialog 
(void *dStorage, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible, 





short procID, WindowPtr behind, 
Boolean goAwayFlag, long refCon, 
Handle items); 


pascal void CloseDialog (DialogPtr theDialog) ; 
pascal void DisposeDialog (DialogPtr theDialog) ; 
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Manipulating Items in Alert and Dialog Boxes 


/* some 


pascal 


pascal 


pascal 
pascal 
pascal 


pascal 


pascal 


pascal 


routines have 2 spellings--see Table 6-1 for the alternate spellings*/ 


void GetDialogItem (DialogPtr theDialog, short itemNo, 
short *itemType, Handle *item, Rect *box); 
void SetDialogItem (DialogPtr theDialog, short itemNo, short 
itemType, Handle item, const Rect *box); 
void HideDialogItem (DialogPtr theDialog, short itemNo); 
void ShowDialogItem (DialogPtr theDialog, short itemNo); 





short FindDialogItem (DialogPtr theDialog, Point thePt); 











void AppendDITL (DialogPtr theDialog, Handle theDITL, 
DITLMethod theMethod) ; 

void ShortenDITL (DialogPtr theDialog, short numberItems) ; 

short CountDITL (DialogPtr theDialog) ; 


Handling Text in Alert and Dialog Boxes 


/* some 


pascal 


pascal 


pascal 


pascal 


pascal 


pascal 


pascal 


pascal 


routines have 2 spellings--see Table 6-1 for the alternate spellings*/ 


void ParamText (ConstStr255Param param0, 
ConstStr255Param paraml, 
ConstStr255Param param2, 
ConstStr255Param param3) ; 
void GetDialogItemText 


(Handle item, Str255 text); 


void SetDialogItemText 
(Handle item, ConstStr255Param text); 


void SelectDialogItemText 








(DialogPtr theDialog, short itemNo, 
short strtSel, short endSel); 
void DialogCut (DialogPtr theDialog) ; 
void DialogCopy (DialogPtr theDialog) ; 
void DialogPaste (DialogPtr theDialog) ; 
void DialogDelete (DialogPtr theDialog) ; 


Handling Events in Dialog Boxes 


/*some 
pascal 
pascal 


pascal 


pascal 


pascal 





routines have 2 spellings--see Table 6-1 for the alternate spellings*/ 
void ModalDialog (ModalFilterProcPtr filterProc, short *itemHit); 
Boolean IsDialogEvent (const EventRecord *theEvent) ; 


Boolean DialogSelect (const EventRecord *theEvent, 
DialogPtr *theDialog, short *itemHit); 


void DrawDialog (DialogPtr theDialog) ; 
void UpdateDialog (DialogPtr theDialog, RgnHandle updateRgn) ; 
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Application-Defined Routines 


pascal void MyItem (WindowPtr theWindow, short itemNo); 
pascal void MyAlertSound (short soundNo) ; 











pascal Boolean MyEventFilter(DialogPtr theDialog, *EventRecord theEvent, 
*short itemHit); 


Assembly-Language Summary 


Data Structures 


DialogRecord Data Structure 


0 dWindow 156 bytes window record for the alert box or dialog box 
156 items long handle to the item list resource for the alert box or dialog box 
160 teHandle long handle to the current editable text item 
164 editField word current editable text item 
166 editOpen word used internally 
168 aDefItem word item number of the default button 


Global Variables 


DAStrings Handles to text strings specified with the ParamText procedure 
DABeeper Address of current sound procedure 

DlgFont Font number for text in dialog boxes and alert boxes 

ACount Alert stage number (0 through 3) of the last alert 

ANumber Resource ID of last alert 

ResumeProc Address of resume procedure (should not be used in System 7) 
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The Finder is an application that works with the system software to keep track of files 
and manage the user’s desktop display. This chapter describes the programming 
interface your application should use to interact with the Finder. 


To use this chapter, you should be familiar with the Resource Manager. See the chapter 
“Introduction to the Macintosh Toolbox” in this book for general information about 
resources; detailed information about the Resource Manager and its routines is provided 
in the chapter “Resource Manager” in Inside Macintosh: More Macintosh Toolbox. Virtually 
all software intended for Macintosh computers must use the Finder-related resources 
described in this chapter. 


Read this chapter to learn how to 
m set up the resources the Finder needs to display and start up your application 


m set up the resources the Finder uses to display information about other files related to 
your application 


m check or change Finder-related information stored in a volume’s catalog file 
m™ support stationery pads 
m use the directories generally organized within the System Folder 


This chapter does not explain how to use Apple events to communicate with the Finder. 
When a user opens or prints a file from the Finder, the Finder sends information to your 
application so that it can open or print the file. In System 7, applications that support 
high-level events receive this information through the required Apple events. 


Refer to Inside Macintosh: Interapplication Communication for instructions on how 

your application should respond to these required Apple events that the Finder sends 
to your application: Open Application, Open Documents, Print Documents, and Quit 
Application. In addition, your application can use another set of Apple events—called 
Finder events—to request services from the Finder. For example, your application can 
ask the Finder to perform such operations as launching another application on your 
behalf. Refer to Inside Macintosh: Interapplication Communication for more details. 


Introduction to the Finder Interface 


The Finder is an application that manages the user’s desktop interface. The desktop is 
the working environment displayed on the Macintosh computer—namely, the gray 
background area on the screen. 


On the desktop, the Finder displays icons representing your application and the 
documents it creates, and it tracks user activity. An icon is an image that the Finder 
displays to graphically represent some object—such as a file, a folder, or the Trash— 
that the user can manipulate. For example, Figure 7-1 on the next page shows icons that 
the Finder displays for several sample applications (called SurfWriter 3.0, SurfPainter, 
and SurfDB) and for a text document (named Some Memo) that a user has created 

with the SurfWriter application. These icons are displayed in a window that the Finder 
uses to display the contents of the disk icon labeled Essentials. 
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Figure 7-1 Application and document icons in a window on the desktop 
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To distinguish your product for the user, you should design your own icons for all the 
files associated with your application. For each file type that your application uses or 
creates, you should define large, small, black-and-white, and 4-bit and 8-bit color icons— 
each in a separate resource. Your application can then use another resource, called a 
bundle resource, to assign these icons to all your files of a particular type. For example, 

the document icon representing Some Memo in Figure 7-1 is the icon that the SurfWriter 
application assigns to all text files that it creates. When double-clicking the icon for Some 
Memo, the user asks the Finder to launch the SurfWriter application, which in tur 
responds by opening the document Some Memo in a window. 


Stationery pads are files that a user creates to serve as templates for other documents. 
Editions are special files that contain data to be shared among applications. Query 
documents contain commands and data in a format appropriate for a database or other 
data source. If your application supports any of these document types, you can create 
icons for the Finder that distinguish the stationery pads, editions, and query documents 
that users create with your application. For example, Plate 4 at the front of this book 
shows customized stationery pad and edition icons used for documents created with the 
SurfWriter application. (Editions are described in Inside Macintosh: Interapplication 
Communication. Query documents are described in Inside Macintosh: Communications.) 


You might also like your application to create customized icons for documents on the 
desktop. Or, if instead of producing an application, you produce and distribute 
information documents (such as database files, stationery pads, query documents, clip 
art libraries, or dictionaries) to be used by other applications, you can also provide 
customized icons for the Finder that distinguish your documents. 


Macintosh users have access to online assistance in the form of help balloons. You can 
customize the help balloon that the Finder displays for your application icon. For 
example, Figure 7-2 shows a customized help balloon for the SurfWriter application icon. 
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Figure 7-2 A customized help balloon for an application icon 
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When appropriate, the Finder starts up your application and uses Apple events to tell 
your application what documents to open or print. To perform these tasks, the Finder 
relies on information you provide through resources. When the user creates or installs a 
file, the File Manager (described in Inside Macintosh: Files) initially stores some of this 
information in the volume’s catalog file. (The catalog file is a special file, located on a 
volume, that contains information about the hierarchical organization of files and folders 
on that volume.) 


The Finder extracts from the catalog file the information you provide in your resources 
and, for quick access to your resource information, the Finder uses that information to 
build either a desktop database for all volumes over 2 MB or a Desktop file for volumes 
under 2 MB. (The desktop database is a Finder-maintained database of icons, file types, 
applications, version data, and comments; the Desktop file is a resource file in which the 
Finder stores this information for volumes under 2 MB.) 


You can even specify resources that identify your application when the user tries to open 
a document and your application is missing. For example, if a user tries to open a 
document named Instructions and the SurfWriter application is missing from the user’s 
computer system, the Finder displays the alert box in Figure 7-3. 


Figure 7-3 A Finder message identifying a missing application 





opened, because the application 
“SurfWriter” could not be found. 


i) The document “Instructions” could not be 





The System Folder is a directory that contains the software that Macintosh computers 
use to start up. The System Folder includes a set of folders for storing related files. Your 
application may use several of these folders for storing its files. For example, you may 
want to use the Preferences folder to store preferences files that your application needs 
when starting up. 
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About the Finder Interface 


You can use the Finder interface to 


m create the resources—such as those describing icons—that the Finder uses to extract 
and to display information about your application and its documents (Generally, all 
applications should provide these resources for their files.) 


m determine and change the Finder information structure stored in a catalog file 
(Generally, most applications need to determine—and many might wish to set-— 
information in the catalog file.) 


m™ support stationery pads so that users can easily use templates for their documents 
(Generally, most applications that create documents should support stationery pads.) 


m locate the directories typically located in the System Folder (Generally, many 
applications will want to access these directories.) 


Using the Finder Interface 


7-6 


The Finder needs quick access to some key information about your application, such as 
what icons to use when displaying your application and its documents. You supply most 
of this information in the resource fork of your application file. 


The Finder extracts this information and uses it to maintain its own database of the 
resources it needs. The Finder records the location of your application on disk in 
this database so that it can find your application quickly when the user opens one of 
your documents. 


For compatibility with the Finder, your application should have 


m asignature resource, so that the Finder can identify and start up your application 
when a user double-clicks documents created by your application 


m aset of resources that describe icons that visually represent your application and 
any documents it creates 


m aset of file reference resources, to link icons with the file types they represent and 
to allow users to launch your application by dragging document icons to your 
application icon 


m abundle resource, to group together your application’s signature, icon, and file 
reference resources 


m asize resource, to tell the Finder how much memory to allocate for your applica- 
tion when it starts up and whether your application supports various system 
software features 


m either a missing-application name string resource in your application’s documents 
(to display the name of your application if the user tries to open or print a document 
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created by your application when your application is missing) or an application- 
missing message string resource in your application’s documents (to explain why 
the user can’t open or print a document used only by your application) 


Note 

Supply a missing-application name string resource for documents 

that you intend for users to open with your application; supply an 
application-missing message string resource for documents (such 

as preferences files) that your application uses but that users 

shouldn’t open. You supply only one of these resources in a document— 
never both. # 


Your application can also make use of these resources: 


m version resources, so that users can easily find out the version of your application and, 
if applicable, the version of your application’s superset of files 


m ahelp resource, which the Finder uses to display your customized Balloon Help 
message for your application, control panel, system extension, or desk accessory icon 


If you sell or distribute data in the form of a document to be used by other applications, 
you can assist users by providing 


m an appropriate file type to allow users to open your document from the Finder by 
dragging its icon to an application icon or by choosing the Open command from the 
File menu within an application 


m the resources describing an icon family to represent your document to the user 


m™ amissing-application name string resource or an application-missing message string 
resource, so the Finder can assist users who try to open or print your documents from 
the Finder 


m version resources, so that users can easily find out the version of your document and, 
if your document file is one of a larger collection of files, the version of the entire 
superset of files 


A catalog file exists on every volume to maintain relationships between the files and 
directories on that volume. (A volume is any storage medium formatted to contain files.) 
Although it’s used mostly by the File Manager, the catalog file also contains information 
used by the Finder. You can always check the information in the catalog file. In 
particular, you may want to check the file type or creator for a file, or you may want to 
check or set one of the Finder flags for a document. When opening a document, your 
application should check a Finder flag to determine if the document is a stationery pad, 
and, if it is, your application should copy the document’s contents into a new document 
and open the new document in an untitled window. 


Your application might wish to use the folders located in the System Folder. Those 
you're most likely to want to access are Preferences, Temporary Items, and Trash. For 
example, you might wish to check for the existence of a user’s configuration file in 
Preferences, create a temporary file in Temporary Items, or—if your application runs out 
of storage when trying to save a file—check how much storage is taken by items in the 
Trash directory and report this to the user. You can use the FindFolder function to get 
the path information you need to gain access to these system-related directories. 
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In System 7, users can create Finder objects called aliases to aid them in organizing their 
files. Ordinarily, when the user wants to open or print files, your application does not 
need to be concerned with whether they are aliases because the Finder resolves aliases 
before passing them to your application. However, if your application bypasses the 
Finder (or the Standard File Package, which is described in Inside Macintosh: Files) when 
manipulating documents, it should check for and resolve aliases itself by using the Alias 
Manager function ResolveAliasFile. 


The rest of this chapter describes in detail how to use these Finder features in your 
application. 


Giving a Signature to Your Application and a Creator anda 
File Type to Your Documents 


The Finder identifies your application through its signature, a unique four-character 
sequence. The signature must not conflict with the signature of any other application. 
To ensure uniqueness, you must register your application’s signature with Apple 
Computer, Inc., at Macintosh Developer Technical Support. 


Note 


There is no need to register your own resource types because they’re 
usually used in only your own applications or documents. 


You must include in your resource file a special resource that has your application’s 
signature as its resource type. By convention, the signature resource has a resource ID 
number of 0. The signature resource typically contains a string that specifies the name, 
version number, and release date of your application. If you do not provide specific 
version information through a version resource (described in “Providing Version 
Resources” beginning on page 7-31), the Finder displays the string stored in the 
signature resource when the user selects your application and chooses Get Info from 
the File menu. 


Listing 7-1 illustrates a signature resource in Rez input format. (Rez is the resource 
compiler provided with Apple’s Macintosh Programmer’s Workshop [MPW], available 
from APDA.) 








Listing 7-1 Rez input for a signature resource 

type 'WAVE' as 'STR '; /*WAVE is the signature*/ 

resource 'WAVE' (0, purgeable) { /*resource ID is 0*/ 
"SurfWriter 3.0 © 1992" /*default Get Info string*/ 

}; 

Note 


The signature resource alone is not sufficient to establish your 
application’s signature. You must also supply a bundle resource, 
described in “Creating a Bundle Resource” beginning on page 7-20. 
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Whenever your application creates a document, it assigns the document a creator and 

a file type. Typically, as described in “Using Finder Information in the Catalog File” 
beginning on page 7-32, your application sets its signature as the document's creator. 
When a user double-clicks a document or selects it and chooses Open or Print from the 
Finder’s File menu, the Finder reads the creator field of that file to find the document’s 
creator. The Finder then searches for an application with a signature by that name. When 
it finds that application, the Finder launches it. 


If the document’s creator is your application’s signature, for example, the Finder calls the 
Process Manager to start your application. The Finder then passes to your application 
the information it needs to open or print the document; since the introduction of 

System 7, the Finder has used Apple events to pass this information to your application. 
Inside Macintosh: Interapplication Communication describes how your application processes 
the required Apple events to open or print files. 


As described in “Using Finder Information in the Catalog File” beginning on page 7-32, 
your application typically assigns a file type to a document when it creates one. The file 
type can be a type especially defined for your application, or it can be one of the existing 
general types, such as those listed here. 


File type 
"APPL' 
"DFIL' 
"DRVR' 
'FFIL' 
'INIT' 
"PECL" 
"PRER' 





"RDEV' 





"TEXT! 
‘adev' 
'appe' 
"cdev' 
"edtp' 
‘edts' 
"edtt' 
is te rl 
“ara 
"kfil' 
"pret * 
"gery' 
"scri' 


"sfil' 


Description 

Launchable application 

File for storing desk accessories 

Driver 

File for storing fonts 

System extension 

QuickDraw picture 

Printer driver 

Chooser extension 

Stream of ASCII characters 

Network extension (such as EtherTalk 2.0) 
Background-only application 

Control panel 

Edition for sharing graphics-oriented data 
Edition for sharing sound-oriented data 
Edition for sharing text-oriented data 
Font 

Script system resource collection 
Keyboard layout 

Preferences file 

Query document for database access 
System extension for script systems 
Sound 
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File type Description 


ec os aly TrueType font 

‘ttro' TeachText read-only file 

'zsys' A system file (such as the System file itself) 
Note 


Apple reserves the use of all signatures and file types whose names 

contain only lowercase and nonalphabetic characters. Your signature 

and the file types created especially for your application must each 

contain at least one uppercase character. Since the system software 

never displays signatures and file types to users, signatures and file 

types can consist of character combinations that might otherwise be 

incomprehensible to anyone but you. # 

Like signatures, file types must be registered with Apple. Your application must have a 
file type of 'APPL'. The creator field of your application file should contain its own 
signature. Most programming environments provide a simple tool for setting the creator 
field of your application file. 


Your application can create documents of any type, and it can specify any application 
as the creator. You could write a utility application, for example, that creates a new 
document by opening one text file and appending onto it another text file. The applica- 
tion would give the new document the same creator as the first original text file so 

that the Finder can call on that application when the user wants to open or print the 
new document. 


Assign the standard file type 'TEXT' to files that consist of only text—that is, a stream of 
characters with return characters at the ends of paragraphs. Most word processors allow 
the user to create text-only files. A document of file type 'TEXT' can be opened or 
printed by any application that accepts such file types. Your application can still assign 
its own signature as the file’s creator so that the Finder can call on it to open or print the 
file when appropriate. 





Users can also open a document created by your application—as well as a document of a 
file type supported by your application—by selecting its icon and dragging it to your 
application’s icon. Because the document'’s file type is stored in the catalog file and the 
Finder stores a list of your application’s supported file types in the desktop database, the 
Finder can determine whether to launch your application. If the document’s file type is 
supported by your application, the Finder launches your application and passes it the 
name of the document. (These topics are detailed in subsequent sections of this chapter.) 


For example, if your application is a page-layout program, it might create documents of 
its own file type while also supporting documents of 'TEXT' and 'PICT' file types. A 
user can launch your application by dragging a document of any of these file types to 
your application icon. 


Your application also relies on file types to determine which files to let the user open 
when your application is running. When your application calls the Standard File 
Package to open a file, your application supplies either a list of the file types that your 
application can open or a filter function for those types. The open file dialog box then 
displays only files of the specified types. (See Inside Macintosh: Files for details.) 
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Creating Icons for the Finder 


The Finder represents your files as icons. To distinguish your product for the user, you 
can design your own icons for all the files associated with your application, including 


m your application file itself 
standard documents created by your application 
stationery pads that users create from your application’s documents 


7 
7 
m data-sharing editions that users create from your application’s documents 

m other special documents, such as read-only, graphics, and query documents, which 
are either created by your Macintosh application or provided by you for use by other 


Macintosh applications 


For most effective display, you should create an icon family for each of your files. 

An icon family is the set of icons that represent a single object, such as an application 
or a document, that the Finder displays. An entire icon family consists of large 
(32-by-32 pixel) and small (16-by-16 pixel) icons, each with a mask, and each available 
in three different versions of color: black and white, 4 bits of color data per pixel, and 
8 bits of color data per pixel. Specifically, the following icons make up the icon family 
for a single file: 


m a large (32-by-32 pixel) black-and-white icon and mask—both of which you define in 
an icon list (' ICN#"') resource 

m asmall (16-by-16 pixel) black-and-white icon and mask—both of which you define in 
a small icon list ('ics#') resource 

m a large (32-by-32 pixel) color icon with 4 bits of color data per pixel—which you 
define in a large 4-bit color icon ('ic14") resource 

m asmall (16-by-16 pixel) color icon with 4 bits of color data per pixel—which you 
define in a small 4-bit color icon ("ics4") resource 

m a large (32-by-32 pixel) color icon with 8 bits of color data per pixel—which you 
define in a large 8-bit color icon ('ic18") resource 


m asmall (16-by-16 pixel) color icon with 8 bits of color data per pixel—which you 
define in a small 8-bit color icon ('ics8") resource 


Plate 3 in the front of this book shows how the SurfWriter sample application uses these 
resources to define the icon family for its application icon. 


Somewhat related to these resources are the icon (' ICON") resource and the color icon 
('cicn') resource. You can use either to describe a 32-by-32 pixel icon within some 
element of your application. However, the Finder does not use or display any resources 
that you create of type 'ICON' or type 'cicn'. Instead, your application uses these 
resources to display icons within your application. Generally, you use an icon resource to 
display a black-and-white icon in a menu or dialog box, as described in the chapters 
“Menu Manager” and “Dialog Manager” in this book. (For example, the color alert box 
in Plate 2 in the front of this book specifies a resource of type 'cicn"' for the color icon 
in the upper-left corner of the alert box.) If you provide a color icon ('cicn") resource 
with the same resource ID as the icon (' ICON") resource, the Menu Manager and the 
Dialog Manager display the color icons instead of the black-and-white icons for users 
with color monitors. 
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Before creating icon families for your files, you should begin by designing a graphic 
element that all of your icon families can share and that can help the users quickly 
identify the files associated with your product. Figure 7-4, for example, illustrates how 
a company uses the image of a wave in all of its application icons; these icons represent 
the SurfWriter text-editing application, the SurfPainter graphics application, and the 
SurfDB database application. As illustrated in Plate 4 at the front of this book, the wave 
element is also included in icons representing the documents, stationery pads, and 
editions that users create with these applications. 


Figure 7-4 Large black-and-white application icons for a company’s product line 





If you do not design your own icons, the Finder uses a set of its own default application 
and document icons for display. Figure 7-5 shows the Finder’s default large black-and- 
white icons. 


Figure 7-5 Default large black-and-white icons 
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Note 

Desk accessories, displayed by default with the icon shown in 

Figure 7-5, were designed for early versions of Macintosh system 
software that did not support cooperative multitasking. Desk 
accessories and applications are much more alike in their appearance 
and behavior in System 7. Because there are no longer any compelling 
reasons for creating desk accessories, you should generally write a 
small application instead of a desk accessory if you wish to create 

a small or simple program. @ 


If you don’t want the Finder to display the default icons for your application or 
documents, you must at least define an icon list (' ICN#"') resource for each icon. 


The term icon list has become a bit of a misnomer, because you can define only two 
images in the icon list resource: a 32-by-32 pixel black-and-white icon and its mask. 

To define color and 16-by-16 pixel icons for a file, you create additional resources, as 
described later in this section. (If you don’t define color versions of your icons, the 
Finder displays the black-and-white icon defined in your icon list resource on all 
displays, and if you don’t define 16-by-16 pixel icons, the Finder algorithmically reduces 
the 32-by-32 pixel icon to half size when needed.) 


An icon list resource defines one icon. It contains two icon descriptions: the actual icon 
for display and an all-black mask that shows the area covered by the icon. The Finder 
uses the mask to crop the icon’s outline into whatever background color or pattern is on 
the desktop. The Finder then draws the icon into this shape. Therefore, it’s important 
that the mask be exactly the same shape as the icon. The mask also defines the area that 
users need to click to select the icon. Therefore, it’s best not to have any holes in the 
mask; otherwise, users may have trouble selecting your icon. 


Figure 7-6 illustrates a black-and-white icon and its mask for an application. The area 
around the pencil just underneath the wave creates a problem with this sample icon and 
its mask: like a hole in a mask, it creates two small areas within the middle of the icon 
that the user cannot select with the cursor. 


Figure 7-6 A black-and-white icon and its mask for an application 
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An icon list resource is defined to be an array of two items of type String[128]; each 
bit in the first array represents a pixel in the 32-by-32 pixel icon, and each bit in the 
second array represents a pixel in the 32-by-32 pixel mask. Typically, you use a high-level 
tool such as the ResEdit application, which is available through APDA, to create your 
icon list resources. Figure 7-7 shows how the icon list resource for the icon in Figure 7-6 
was created using the ResEdit icon editor. When you are satisfied with the appearance of 
your icons, you can use the DeRez decompiler to convert your icon list resources into 
Rez input. 


Listing 7-2 is a partial listing of the icon list resource’s Rez input that describes the 
application icon shown in Figure 7-7; Listing 7-2 also shows partial listings for the icon 
list resources used for the icons that represent the documents created by the application. 
This listing and those that follow in this chapter use Rez input format to help you 
understand the format of the resources and see how they work together. 


Figure 7-7 The ResEdit view of an icon 











Listing 7-2 Rez input for an icon list resource 


data 'ICN#' (128, purgeable) { /*application icon & mask*/ 
/*array: 2 elements*/ 
/*[1]: the application icon*/ 
S"0E 00 00 00" /*1st line of icon: 4 bytes (32 bits) */ 
/*32 lines total in icon*/ 


, /*[2]: the mask*/ 
S"0E 00 00 00 /*1st line of mask: 4 bytes (32 bits) */ 
/*32 lines total in mask*/ 


i 
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data 'ICN#' (129, purgeable) { /*text document icon and mask*/ 
/*icon data goes here*/ 

}; 

data 'ICN#' (130, purgeable) { /*stationery pad icon & mask*/ 
/*icon data goes here*/ 

}; 

data 'ICN#' (131, purgeable) { /*edition icon & mask*/ 
/*icon data goes here*/ 

}; 


You can also define a small (16-by-16 pixel) version of your icon in a small icon list 
resource (that is, in a resource of resource type 'ics#'). On black-and-white monitors, 
the Finder displays the small icon in windows when the user chooses by Small Icon 
from the View menu. On black-and-white monitors, the small icon also appears in the 
Application menu after the user launches your application and in the Apple menu if 
the user places your application or an alias to it in the Apple Menu Items folder. (Alias 
files and the Apple Menu Items folder are described, respectively, in “Using Aliases” 
beginning on page 7-39 and “Using the System Folder and Its Related Directories” 
beginning on page 7-41.) 

You should also define color versions of both large and small icons by using several 
resource types. The resource for each icon variation has the same resource ID as the icon 
list resource that defines the large black-and-white icon. For example, if the resource ID 
number of your application icon’s icon list resource is 128, its small icon list resource 
should have a resource ID number of 128; and the following resources should also have 
resource IDs of 128: the large 4-bit color icon resource, the small 4-bit color icon resource, 
the large 8-bit color icon resource, and the small 8-bit color icon resource. 


Don’t define masks for the resources that define color icons. The large 4-bit color icon 
resource and large 8-bit color icon resource use the black-and-white icon mask defined in 
their companion icon list resource, and the small 4-bit color icon resource and small 8-bit 
color icon resource use the black-and-white icon mask defined in their companion 
'ics#' resource. Because of this, the outline shapes of your color icons should exactly 
match those defined in your 'ICN#' and 'ics#"' resources. 


ResEdit 2.1 includes an icon family editor to help you easily manage the creation of these 
related resources. See the ResEdit Reference for details. 


See Macintosh Human Interface Guidelines for information about the most effective use of 
color and shape for your icons. It is generally best that you first create the black-and- 
white icons in the icon list resource and small icon list resource and then add color to 
them using the resources that define color icons. Don’t alter the shapes of your icons 
among these resources; otherwise, the masks defined in the icon list resource and the 
small icon list resource won’t match these shapes. Choose your colors from the 36 
recommended icon colors in the system palette. (If you use ResEdit 2.1, these colors 
appear in a palette when you choose Apple Icon Colors from the Color menu.) Note that 
you cannot specify your own color table for these resources. 


For more information about color palettes, see Inside Macintosh: Imaging. Although the 
Palette Manager allows you to define a palette for the system to use when it needs to 
define the color environment, you should rely on the system palette colors for your 
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icons. Users may often use the Finder when your application is not running, and the user 
can switch to another application when your application is running. Relying on the 
system palette gives your icons a more consistent look in the Finder regardless of what 
the active application is. Also, because users can change the desktop color and pattern, 
your application gives users more control over their work environment if your icons rely 
on the system palette. Users can always alter your color definitions by selecting an icon 
and choosing a color from the Label menu. The Finder then blends the chosen color into 
those of the selected icon. To restore the original colors, users must choose None from 
the Label menu. 


If your application creates documents, it should also define at least two additional icon 
families: one to be displayed for documents created by your application and another 
to be displayed when the user creates a stationery pad from one of your applica- 

tion’s documents. (“Supporting Stationery Pads” beginning on page 7-34 describes 
stationery pads.) 


If your application creates other variations of its documents, you can assist your users 
by providing different icons for the different documents. For example, TeachText has 
separate icon families to distinguish its read-only and graphics documents. 


If your application supports data sharing through the Edition Manager, your application 
should also define an icon family for editions. The Edition Manager (described in Inside 
Macintosh: Interapplication Communication) allows users to share and automatically 
update data from numerous documents and applications. For example, a user might 
want to capture sales figures and totals from within a spreadsheet and then include this 
information in a word-processing document that summarizes sales for a given month. If 
both the spreadsheet and word-processing applications support the Edition Manager, the 
user begins by selecting data within the spreadsheet document and creating a publisher. 
The spreadsheet application then writes a copy of that data to a separate file, called an 
edition. The edition is represented by an icon; by default, it appears as the edition icon 
shown in Figure 7-5 on page 7-12. If the user opens a word-processing document and 
creates a subscriber to the spreadsheet document’s edition, the word-processing 
application then incorporates the desired sales figures and totals from the spreadsheet 
document’s edition into the document. 


If you design your application to create editions, consider creating an icon that uniquely 
identifies your editions and that associates them with your application’s documents. The 
file type for your edition containers should be 'edtt' (for text-oriented data), 'edtp' 
(for graphics-oriented data), or 'edts' (for sound-oriented data); and the creator, of 
course, should be the signature of your application. 


If your Macintosh application is a database program or serves as a source for data (as 
a spreadsheet program often does), you might wish to create query documents so that 
other Macintosh applications can gain access to that data through the Data Access 
Manager; in this case, your application should also define an icon family for its query 
documents. (See Inside Macintosh: Communications for information on sharing data in 
this manner.) 


Plate 4 at the front of this book shows the large color icons for the various documents 
that the sample SurfWriter application creates: text documents, stationery pads, 
and editions. 
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Defining icon resources is not enough to display your icons. In addition, you must 
follow one of two sets of procedures: 


m If you are an application developer, you must define file reference resources and a 
bundle resource for your application, as described in “Creating File Reference 
Resources” beginning on page 7-18 and “Creating a Bundle Resource” beginning on 
page 7-20. 

m If you are an information provider or a database developer—that is, if you provide 
documents that are used by other applications—you don’t need to create file reference 
resources or a bundle resource to provide document icons on Macintosh computers 
running System 7. You can instead create customized icons for your documents as 
described in the following section. 


Creating Customized Document Icons 


You can create customized icons for your documents. Users can also create customized 
icons. When an icon list resource is stored with a resource ID of —16455 in the resource 
fork of a file, the Finder uses the large, small, 4-bit and 8-bit color, and black-and-white 
icons defined in resources with that resource ID as customized icons in place of the 
Finder’s default icon and in place of any icons listed in the file’s bundle resource. 


Note 

Although an application can assign icons to it all of its documents by 
associating their icons with the documents’ file types in a bundle 
resource (as explained in “Creating File Reference Resources” beginning 
on page 7-18 and “Creating a Bundle Resource” beginning on 

page 7-20), a customized icon can represent only one specific file—that 
file that has an icon list resource with a resource ID of —16455 in its 
resource fork. @ 


Users of System 7 are able to customize individual icons. By selecting a file and choosing 
Get Info from the File menu, the user sees the information window for that file. The 

user can then select the icon displayed in the upper-left corner of the information 
window and use the Paste command in the Edit menu to replace it with a picture from 
the Clipboard. The Finder creates a family of icons based on the user’s customized 

icon, assigns a resource ID number of —16455 to each resource in the icon family, stores 
these resources in the resource fork of the file that the icon represents, and sets the 
hasCustomIcon bit in the file’s Finder flags field. (Finder flags are described in detail 
in “File Information Record” beginning on page 7-47.) 


Your application can use the same strategy to provide customized icons for the 
documents that it creates. For example, a drawing application might create miniature 
versions of the illustrations contained within its documents and use those for the 
documents’ icons. 


If you are a database developer who creates and distributes query documents that 
support the Data Access Manager, you can also use this strategy to create icons that 
identify your database’s query documents. Similarly, if instead of producing an 
application you produce and distribute information (such as database files, stationery 
pads, clip art libraries, or dictionaries) to be used by other applications, you might want 
to provide icons that distinguish your documents. 
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To make the Finder display customized icons for a document, you must create—at least— 
an icon list resource with resource ID —-16455 and store it in the document’s resource 

fork. (To create this while your application is running, your application can call the 
AddResource procedure, described in the chapter “Resource Manager” in Inside 
Macintosh: More Macintosh Toolbox.) You can use the following constant in place of 

the ID number: 


CONST kCustomIconResource = -16455; {res ID for custom icon} 


If you provide only an icon list resource, the Finder uses a black-and-white icon on all 
screen displays and automatically reduces it when a small version of the icon is required. 
To create color versions and to define a small version of the icon, create an entire icon 
family as described in “Creating Icons for the Finder” beginning on page 7-11. 


After creating resources for icons using the kCust omIconResource constant as their 
IDs, you must set the hasCustomIcon bit in the file’s Finder flags field. To prevent 
users from changing these icons, set the nameLocked bit in the file’s Finder flags field. 
(Most development environments provide tools for setting these bits. “Using Finder 
Information in the Catalog File” beginning on page 7-32 describes how to determine 
and set these Finder flags.) 


Creating File Reference Resources 


File reference ('FREF') resources perform two main functions. First, they associate icons 
you define with file types used by your application. Second, they allow users to drag 
document icons to your application icon in order to open them from your application. 


Create a file reference resource for your application file itself and create separate file 
reference resources for each file type that your application can open. Listing 7-3 shows, 
in Rez input format, the file reference resources for the SurfWriter application file, text 
documents, stationery pads, and editions and for TeachText read-only documents. 


Each file reference resource specifies the following items: 

m a file type 

m the local ID of an icon list resource as assigned in the bundle resource 

m@ an empty string 

The file type can be defined for files created by your application only, for files created by 
other applications that your application supports, or for files of the existing general 
types, suchas 'TEXT' and 'PICT'. 

As described in the next section, “Creating a Bundle Resource,” the local ID maps the 
file type to an icon list resource that is assigned the same local ID in the bundle resource. 
If you wanted two file types to share the same icon, for example, you could create two 
separate file reference resources that share the same local ID, which the bundle resource 
would map to the same icon list resource. (Creating two file types that share the same 


icon is not recommended, however, because a shared icon would make it very difficult 
for the user to distinguish between the different file types while using the Finder.) 
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Listing 7-3 Rez input for file reference resources 


resource 'FREF' (208, purgeable) { /*SurfWriter application*/ 
'APPL', /*type 'APPL'*/ 
0, /*maps to icon list resource w/ local ID 0 in bundle resource*/ 
we 


/*leave empty string for name: not implemented*/ 
}; 





resource 'FREF' (209, purgeable) { /*SurfWriter document*/ 
'TEXT', /*type 'TEXT'*/ 
diy /*maps to icon list resource w/ local ID 1 in bundle resource*/ 


wie 

}; 

resource 'FREF' (210, purgeable) { /*SurfWriter stationery pad*/ 
"SEXT', /*type 'SEXT'*/ 


2, /*maps to icon list resource w/ local ID 2 in bundle resource*/ 





}; 
resource 'FREF' (211, purgeable) { /*SurfWriter edition*/ 
Tedtt', /*type 'edtt'*/ 
3, /*maps to icon list resource w/ local ID 3 in bundle resource*/ 


}; 
resource 'FREF' (212, purgeable) {/*TeachText read-only files*/ 
"ttro', 4, "" /*These documents have TeachText as their */ 
/* creator. Finder uses TeachText's icon list resource */ 
/* for these documents. Included here so users */ 
/* can drag these docs to SurfWriter's app icon*/ 
}; 


If you provide your own icon for the stationery pads that users create from your 
application’s documents, create a file reference resource for your stationery pads. 
Assign this file reference resource a file type in the following manner: use the file type 
of the document upon which the stationery pad is based, but replace the first letter of 
the original document’s file type with a lowercase s. As with other file reference 
resources, you map this to an icon list resource in the bundle resource. (This convention 
necessitates that you make the names of your documents’ file types unique in their last 
three letters.) 


For example, in Listing 7-3, the 'sEXT' file type assigned within the file reference 
resource is used for stationery pads created from documents of the 'TEXT' file type. In 
this case, when the isStationery bit (described in “Using Finder Information in the 
Catalog File” beginning on page 7-32) is set on a document of file type 'TEXT', the 
Finder looks in the SurfWriter application’s bundle ('BNDL") resource to determine 
what icon is mapped to documents of type 'sEXT'. The Finder then displays the 
document using the stationery pad icon shown in Plate 4 at the front of this book. 
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When the user drags a document icon to your application icon, the Finder checks a list 
that it maintains of your file reference resources. If the document’s file type appears in 
this list, the Finder launches your application with a request to open that document. 


If your application supports file types for which it doesn’t provide icons, you can still 
define file reference resources for them, and then users can launch your application by 
dragging these document icons to your application icon. For example, the file reference 
resource with resource ID 212 in Listing 7-3 on page 7-19 is created so that the Finder 
launches the SurfWriter application when users drag TeachText read-only documents to 
the SurfWriter application icon. Since these documents have TeachText as their creator, 
the Finder displays the icon that the TeachText application defines for them in its own 
bundle resource. 


By supporting the Open Documents event, you can also specify disks, folders, and a pair 
of wildcard file types in your file reference resources so that users can launch your 
application by dragging their icons to your application icon. As explained in Inside 
Macintosh: Interapplication Communication, the Open Documents event is one of the four 
required Apple events. After the Finder uses the Process Manager to launch an 
application that supports high-level events, the Finder sends your application an Open 
Documents event, which includes a list of alias records for objects that the application 
should open. 


Because alias records can specify volumes and directories as well as files, an Open 
Documents event gives you the opportunity to handle cases in which users drag disk 
or folder icons to your application. (Alias records are described in “Using Aliases” 
beginning on page 7-39.) Create a file reference resource and specify 'disk' as the 

file type to allow users to drag hard disk and floppy disk icons to your application icon. 
Create a file reference resource and specify 'fold' as the file type to allow users to 
drag folder icons to your application icon. 


You can create a file reference resource that specifies '****' as the file type to allow 
users to drag all file types—including applications, system extensions, documents, and 
so on, but not including disks or folders—to your application icon. If you create three file 
reference resources that specify 'disk', 'fold',and '****' as their file types and if 
your application supports the Open Documents event, you effectively allow users to 
launch your application by dragging any icon to your application icon. It is up to your 
application to open disks, folders, or all possible file types in a manner appropriate to the 
needs of the user. 


Creating a Bundle Resource 


A bundle ('BNDL') resource associates all of the resources used by the Finder for your 
application; in particular, it associates your application and its documents with their 
icons. The bundle resource contains 


m the application’s signature 
m the resource ID number of its signature resource (which should always be 0) 


m the assignment of local IDs to the resource IDs of all icon list resources defined for the 
application; the local IDs must be the same as those assigned within corresponding 
file reference resources 
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m the assignment, for compatibility reasons, of local IDs to file reference resource [Ds 
(For consistency, these can be the same local IDs that are assigned inside the file 
reference resources, but they don’t have to be—they only need to be unique for every 
file reference resource.) 


When the Finder first displays your application on the user’s desktop, it checks the 
catalog file (described in detail in “Using Finder Information in the Catalog File” 
beginning on page 7-32) to see if your application has a bundle resource. If it doesn’t, 
the Finder displays the default icons shown in Figure 7-5 on page 7-12. If your 
application has a bundle resource, the Finder installs the information from the bundle 
resource and all its bundled resources into either the desktop database for a hard disk 
or into the Desktop file for a floppy disk and uses this information to display icons for 
the file types associated with your application. 


You must assign local IDs to your icon list resources within your bundle resource. Make 
sure that for all your file types with icons, these local IDs match the local IDs you 
assigned inside their corresponding file reference resources. In the Desktop file on floppy 
disks (and on hard disks running earlier versions of system software), the Finder 
renumbers the resource IDs that you’ve assigned to your resources to avoid conflicts 
with the resources of other applications. Therefore, the bundle resource has to rely on 
these local IDs to map icon list resources to their file reference resources; that is, the 
bundle resource uses the local ID you assign to an icon list resource to map it to the file 
reference resource that has specified the same local ID. 


For example, the file reference resource with resource ID 208 in Listing 7-3 on page 7-19 
shows that the file type 'APPL"' (the SurfWriter application file) is assigned a local ID 
of 0. In the bundle resource shown in Listing 7-4, you see that local ID 0 is assigned to 
the icon list resource with resource ID 128. This maps the icon defined by this resource 
(see Figure 7-7 on page 7-14) to the SurfWriter application file. Listing 7-4 shows 

the bundle resource for the icons and file reference resources defined in Listing 7-2 on 
page 7-14 and in Listing 7-3 on page 7-19. 


Listing 7-4 Rez input for a bundle resource 

resource 'BNDL' (128, purgeable) { /*SurfWriter bundle resource*/ 
"WAVE', /*SurfWriter signature*/ 
0, /*resource ID of signature resource: should be 0*/ 


{ 
"ICN#', { /*mapping local IDs in 'FREF's to 'ICN#' IDs*/ 
0, 128, /*'FREF' w/ local ID 0 maps to 'ICN#' res ID 128*/ 
1, 129, /*'FREF' w/ local ID 1 maps to 'ICN#' res ID 129*/ 
2, 130, /*'FREF' w/ local ID 2 maps to 'ICN#' res ID 130*/ 
3, 131 /*'FREF' w/ local ID 3 maps to 'ICN#' res ID 131*/ 
/*no ‘FREF' with local ID 4 in this list: */ 


/* TeachText's icons used for 'ttro' file type*/ 








}, 
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'FREF', { /*local res IDs for 'FREF's: no duplicates*/ 
10, 208, /*local ID 10 assigned to 'FREF' res ID 208*/ 
11, 209, /*local ID 11 assigned to 'FREF' res ID 209*/ 
12, 210, /*local ID 12 assigned to 'FREF' res ID 210*/ 
13, 211, /*local ID 13 assigned to 'FREF' res ID 211*/ 
14, 212 /*local ID 14 assigned to 'FREF' res ID 212*/ 











}; 


In Listing 7-4, notice that you also assign local IDs to file reference resources inside the 
bundle resource. This assignment is superfluous because the Finder doesn’t map these 
local IDs to any other resources. The local ID assignment for file reference resources 
inside the bundle resource was implemented for the earliest versions of Macintosh 
system software, and it remains this way today to maintain backward compatibility. For 
compatibility with the format of the bundle resource, assign local IDs to file reference 
resource IDs. You may number them any way you like, except that each local ID in this 
particular list must be unique. 


Of all the icon resource types that make up an icon family, you need to list only the icon 
list resource in the bundle resource. The Finder automatically recognizes and loads all 
the other members of the icon family—provided that you have given them the same 
resource IDs that you have assigned to your icon list resource. 


If the user drags documents created by other applications to your application icon, and 

if you have created file reference resources for these documents’ file types, the Finder 
launches your application and passes it the names of the documents. You should create 
file reference resources for all file types that your application supports. Do not provide 
icon resources for file types created by other applications because the Finder won’t use 
them, but will instead use the icon resources defined by the documents’ creators. Though 
the local IDs of such a file reference resource are superfluous in the file reference resource 
and at the bottom of the bundle resource, the resource formats require that you provide 
local IDs in both. 


For example, notice in Listing 7-3 on page 7-19 that the file reference resource with 
resource ID 212 is assigned a local ID of 4, but that no icon list resource is assigned to 
local ID 4 in the bundle resource in Listing 7-4 on page 7-21. This file reference resource, 
which specifies a file type of 'ttro', was created in Listing 7-3 to make the Finder 
launch the SurfWriter application when users drag TeachText read-only documents to 
the SurfWriter application icon. No icon mapping is made for this file type in the 
SurfWriter application’s bundle resource because the Finder displays the icons defined 
for it by the TeachText application. The file reference resource with resource ID 212 is 
assigned to local ID 14 in the bundle resource in Listing 7-4 because the format of the 
resource requires a local ID for all associated file reference resources. 


You alert the Finder that your application has a bundle resource by setting a bit in the 
file’s Finder flags field. (Most development environments provide a simple tool for 
setting the bundle bit. “Using Finder Information in the Catalog File” beginning on 
page 7-32 describes Finder flags.) 
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Figure 7-8 illustrates how the bundle resource created in Listing 7-4 uses local IDs to 
map icon list resources to file reference resources. This figure illustrates two main 
concepts: first, that one bundle resource ties together all the icon resources and file 
reference resources for your application and all of its documents; and second, that the 
icon resources and their associated file reference resources are mapped together by 
local IDs. 


Figure 7-8 Linking icon list resources and file reference resources in a bundle resource 
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In Figure 7-8, the application file’s icon list resource has resource ID 128 while its file 
reference resource has resource ID 208. For easier code maintenance, you should 
probably assign the same resource ID to a file’s file reference resource that you assign 

to its icon list resource. However, because the Finder renumbers these whenever it 

adds them to a Desktop file on floppy disks, you must map them by using local IDs. In 
Figure 7-8, the application file’s icon list resource is assigned local ID 0. This maps the 
icon to the file type described by the file reference resource with local ID 0—in this case, 
the file reference resource with resource ID 208. 


The general steps you must take to provide icons for applications and documents are 
enumerated here and assume that you are using a tool, such as ResEdit, that allows you 
to open and edit several resources simultaneously. (Remember that these resources must 
have resource IDs of 128 or greater.) 


To provide your application with icon families for itself and for its documents, follow 
these steps: 


1. Design a graphic element that all of your icon families can share in common and that 
can help users quickly identify the files associated with your product. 


2. Create an icon list ('ICN#') resource for your application file. 


3. Create the other members of the icon family of the application file—resources of types 
"‘ics#', 'icl8', 'icl4', 'ics8',and 'ics4'—and give each of these the same 
resource ID as the icon list resource. 


4. Create a bundle ('BNDL"') resource. 


5. Within the bundle resource, list the resource ID number of the application file’s icon 
list resource and assign it a local ID of 0. 


6. Create a file reference resource for the application file. 


7. Within the file reference resource, assign the application a file type of 'APPL' and 
assign it a local ID of 0. 


8. Within the bundle resource, list the resource ID number of the file reference resource 
for the application file and assign it a unique local [D—for example, 0 to maintain 
consistency with the local ID assigned in the file reference resource. 


9. Create another icon family—consisting of resources of types 'ICN#', 'ics#', 
"icl8', 'icl4', 'ics8',and 'ics4'—to represent one type of document that 
your application creates. 


10. Within the application’s bundle resource, list the resource ID number of the 
document’s icon list resource and assign it a local ID of 1. 


11. Create a file reference resource for the document. 


12. Within the file reference resource for the document, assign it a file type (for example, 
'TEXT' or 'edtt') and assign it a local ID of 1. 





13. Within the bundle resource, list the resource ID number of the file reference resource 
for the document and assign it a unique local ID—for example, 1 to maintain 
consistency with the local ID assigned in the file reference resource. 


14. Assigning unique local IDs for every type of document your application creates, 
repeat steps 9 through 13. 


Using the Finder Interface 


CHAPTER 7 


Finder Interface 


15. If your application supports file types of other applications, define file reference 
resources for them, but do not create icon resources for them. 


16. Create a signature resource (as described in “Giving a Signature to Your Application 
and a Creator and a File Type to Your Documents” beginning on page 7-8) with 
resource ID 0. 


17. Set the file’s hasBundle bit and clear the hasBeenInited bit in the file’s Finder 
flags. (Finder flags are described in “Using Finder Information in the Catalog File” 
beginning on page 7-32.) 





18. Save and close all of the resources. (When you restart your Macintosh computer, your 
application should appear with its own icon. If you later alter any of your icons, clear 
the hasBeenInited bit and rebuild your desktop database by pressing Command- 
Option when restarting.) 


How and When the Finder Launches Your Application 


The previous sections in this chapter explain the resources that the Finder uses to display 
and launch your application. This section provides a brief summary of how the Finder— 
using the previously described resources—starts up your application whenever the user 
requests the Finder to launch your application or to open or print a document supported 
by your application. 


The simplest scenarios under which the Finder launches your application occur when 
the user double-clicks your application icon or selects it and chooses Open from the 
Finder’s File menu. In these cases, the Finder calls the Process Manager to start your 
application. As explained in Inside Macintosh: Processes, the Process Manager creates a 
partition of memory for your application, loads your code into this partition, and sets up 
the stack, heap, and A5 world for your application. The Process Manager returns control 
to the Finder. 


If your application supports the required Apple events (as explained in Inside Macintosh: 
Interapplication Communication), the Finder sends your application an Open 

Application event and then relinquishes control to your application. Your application 
then performs the tasks necessary to open itself—displaying an untitled document 
window, for example. 


When the user requests the Finder to open or print a document supported by your 
application, the Finder calls the Process Manager and launches your application in the 
same way, except that the Finder sets up the information your application needs to open 
or print the document and passes this information to your application. This information 
includes a list of files to open or print. In System 7, applications receive this information 
through Apple events, which are described in Inside Macintosh: Interapplication 
Communication. 


The user can request the Finder to open documents created by your application by 
double-clicking one of their icons, and the user can request the Finder to open or print 
documents by selecting one or more icons and choosing Open or Print from the Finder’s 
File menu. The Finder reads the creator field of each selected file to find the document’s 
creator. Typically (as described in “Using Finder Information in the Catalog File” 
beginning on page 7-32), your application sets the four-character string specified in its 
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signature resource as the creator of its documents. The Finder searches for the applica- 
tion whose signature matches each document's creator. If the document’s creator 
matches your application’s signature, the Finder calls the Process Manager, launches 
your application, and then passes your application the name of the selected document 
or selected multiple documents in an Open Documents or a Print Documents event. 
Your application should then open the documents in titled windows or print them, as 
appropriate. (See Inside Macintosh: Files for detailed information about opening 
documents; see Inside Macintosh: Imaging for detailed information about printing them.) 


If the user tries to open documents created by your application and your application is 
missing, the Finder displays an alert box telling the user that your application is missing. 
The Finder displays the name of your application in this alert box if you provide your 
documents with a missing-application name string resource, as described in “Displaying 
Messages When the Finder Can’t Find Your Application” beginning on page 7-27. 


Sometimes when your application is already running, the user might double-click a 
document created by your application. In this case, the Finder sends your application 
the Open Documents event. 


The user can also request the Finder to launch your application by dragging one icon or 
several icons to your application’s icon. The Finder determines whether to launch your 
application by comparing the document's file type (which is stored in the catalog file) 
against the list of your application’s supported file types. The Finder compiles this list 
from the file reference resources you create for your application; the Finder stores this 
list in the desktop database. If the document's file type appears in the file reference 
resource list for your application, the Finder calls the Process Manager, launches your 
application, and passes it the name of the selected document or selected multiple 
documents in an Open Documents event. Your application should then open the 
documents in titled windows. 


You can also specify disks, folders, and a wildcard file type for all other files in your file 
reference resources so that users can launch your application by dragging their icons to 
your application icon, in which case the Finder launches your application and sends it an 
Open Documents event. An Open Documents event includes a list of alias records for ob- 
jects that the application should open. It is up to your application to open disks, folders, 
or all possible file types in a manner appropriate to the needs of the user. (Alias records 
are described in “Using Aliases” beginning on page 7-39.) 

To support stationery, your application should specify the isStationeryAware 
constant in its 'SIZE' resource and always check the isStationery bit of a document 
passed to it by the Finder. If the isStationery bit is set for a file that the user wants to 
open, your application should copy the stationery pad’s contents into a new document 
and open the document in an untitled window. This is described in “Supporting 
Stationery Pads” beginning on page 7-34. 

In System 7, users can create aliases, which are objects that represent other files, 
directories, or volumes. If the user opens an alias that represents a document created by 
your application, the Finder resolves the alias for you; that is, it passes your application 
the name and location of the document itself, not the alias. 
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Displaying Messages When the Finder Can’t Find 
Your Application 


When the user double-clicks a file or selects it and chooses either the Open or the Print 
command from the Finder’s File menu, the Finder looks for the application whose 
signature is stored in the file’s creator field. The Finder starts up that application and 
tells it which documents the user wants to open or print. If the Finder cannot find the 
creator application, it displays an alert box. 





If the document is of file type 'TEXT' or 'PICT' and if the TeachText application is 
available, an alert box asks the user whether the TeachText application should be 
used to open the document. For documents of any other file type, or if the TeachText 
application is not present, the Finder displays an alert box like the one shown in 
Figure 7-9. Your application should store one of two string resources in its documents 
to make the alert box message more useful than the default shown in Figure 7-9. 


Figure 7-9 The default application-unavailable alert box 





The document “Instructions” could not be 
opened, because the application program 
that created it could not be found. 





Before displaying the default message shown in Figure 7-9, the Finder looks in the 
document for one of two special 'STR_ ' resources with resource ID numbers of -16396 
and —16397: the missing-application name string and the application-missing message 
string, respectively. If the Finder can’t find the document’s creator on any mounted 
volume, it looks first for the application-missing message string resource. Provide an 
application-missing message string resource if you do not intend for users to open the 
file. The message should explain why the file can’t be opened. If the Finder does not find 
an application-missing message string resource, it looks for the missing-application 
name string resource. Provide a missing-application name string resource if you intend 
for users to open the file. The missing-application name string should be your applica- 
tion’s name; the Finder displays it in an alert box to inform the user that your application 
is needed. 


Supply either the application-missing message string resource or the missing-application 
name string resource; don’t supply both. Supply an application-missing message string 
resource for documents (such as a preferences file) that your application uses but that 
users should not open; supply a missing-application name string resource for documents 
that you intend for users to open with your application. 


Your missing-application name string resource (an 'STR ' resource with a resource ID 
number of —16396) should contain the name of your application. Listing 7-5 on the next 
page shows a missing-application name string resource for the SurfWriter application. 


Using the Finder Interface 7-27 


7-28 


CHAPTER 7 


Finder Interface 


Listing 7-5 Rez input for a missing-application name string resource 
resource 'STR ' (-16396, purgeable) { /*the application name*/ 
"SurfWriter" 


he 


You can store this resource in the resource fork of your application. When your applica- 
tion saves a document for the first time, it should copy the missing-application name 
string resource from your application’s resource fork to the resource fork of the newly 
created document. Listing 7-6 shows a fragment of an application-defined function 
called DoSaveAsCmd, which the application calls when the user chooses the Save As 
command from the File menu. (For a description of the File Manager routines used here 
to create, open, and save the resource file, see Inside Macintosh: Files.) 


Listing 7-6 Storing a missing-application name string resource in the resource fork of 
a document 
VAR 
myData: MyDocRecHnd; {handle to document record} 
myErr: OSErr; 
myFile: Integer; {file reference number} 





{with the DoSaveAsCmd routine: create document's resource fork} 
FSpCreateResFile(myData®**.fileFSSpec, 'MYAP', 'TEXT', 
smSystemScript) ; 























myErr := ReskError; 
IF myErr = noErr THEN {open the resource fork} 
myFile := FSpOpenResFile(myData**.fileFSSpec, fsRdWrPerm) ; 
IF myFile > 0 THEN {copy the missing-application name string} 
myErr := DoCopyResource('STR ', -16396, gAppsResFile, myFile) 
ELSE 
myErr := Reskrror; 








IF myErr = nokrr THEN 
myErr := FSClose(myFile); {close the resource fork} 


Listing 7-7 shows the application-defined function DoCopyResource, which copies the 
missing-application name string resource from the application’s resource fork into the 
newly created document's resource fork. (For a description of the Resource Manager 
routines used here to set, open, and write the resource file, see the chapter “Resource 
Manager” in Inside Macintosh: More Macintosh Toolbox.) 
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Listing 7-7 Copying the missing-application name string resource into the resource fork of 
a document 


FUNCTION DoCopyResource (theType: ResType; theID: Integer; 
source: Integer; dest: Integer): OSErr; 











VAR 
myHandle: Handle; {handle to resource to copy} 
myName: Str255; {name of resource to copy} 
myType: ResType; {ignored; used for GetResInfo} 
myID: Integer; {ignored; used for GetResInfo} 
BEGIN 
UseResFile (source) ; {set the source resource file} 
myHandle := GetResource(theType, thelID); {open the source} 
IF myHandle <> NIL THEN 
BEGIN 
GetResInfo(myHandle, myID, myType, myName) ; {get resource } 
{ name} 
DetachResource (myHandle) ; {detach resource} 
UseResFile (dest) ; {set the destination resource file} 


AddResource(myHandle, theType, theID, myName) ; 
IF ResError = noErr THEN 





WriteResource (myHandle) ; {write resource data} 
END; 
DoCopyResource := ResError; {return result code} 
END; 


If a user tries to open or print one of the application’s documents when the application is 
not present, the Finder specifies the application’s name in the alert box, as illustrated in 
Figure 7-10. 


Figure 7-10 The application-unavailable alert box specifying an application’s name 





The document “Instructions” could not be 
opened, because the application 
“SurfWriter” could not be found. 





Your application-missing message string resource (an 'STR ' resource witha 
resource ID number of -16397) should explain why the user cannot open or print a 
document. Use this resource for files—such as your application’s preferences file— 
that are not intended to be opened or printed by the user. Register a signature (as 
explained in “Giving a Signature to Your Application and a Creator and a File Type to 
Your Documents” beginning on page 7-8) that is different from the signature of your 
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application and set this signature as the creator of files that you don’t want your users to 
open. This ensures that the Finder displays your message instead of launching your 
application when the user double-clicks these documents. 


Listing 7-8 illustrates an application-missing string resource that explains why a user 
cannot open a preferences file. 


Listing 7-8 Rez input for an application-missing message string resource 


resource 'STR ' (-16397, purgeable) {/*the message*/ 

"This document describes user preferences for the application " 
"SurfWriter. You cannot open or print this document. To be " 
"effective, this document must be stored in the Preferences " 
"folder in the System Folder." 

}; 


Figure 7-11 shows the alert box generated by Listing 7-8. 


Figure 7-11 The application-unavailable alert box with a customized message 





This document describes user preferences 
for the application SurfWriter. You cannot 
open or print this document. To be 
effective, this document must be stored in 
the Preferences folder in the System 


Folder. 








Note that if your application creates documents of file type 'TEXT' or 'PICT', if 
the TeachText application is available, and if your application is missing when the 
user tries to open these documents from the Finder, the Finder always displays the 
alert box shown in Figure 7-12. For these file types, the Finder displays this alert box 
even if you provide missing-application name string resource or application-missing 
message string resource. 


Figure 7-12 The application-unavailable alert box for 'TEXT' and 'PICT' documents 





The document “Instructions” could not be 
opened, because the application program 
that created it could not be found. Do you 


want to open it using “TeachText”? 
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Providing Version Resources 


You can use version ('vers') resources to record version information for your 
application. If the user opens the Views control panel, clicks the Show version box, and 
then chooses any command from the View menu other than by Icon or by Small Icon, 
filenames and their version numbers from the version resource appear in the active 
Finder window. The Finder also displays version information when the user selects your 
application and chooses Get Info from the File menu. 


The version resource allows you to store a version number, a version message, and a 
region code. (Because the Get Info command’s information window already displays 
the name of your application, the version message should not include the name of 
your application.) You can use version resources to assign version information to an 
individual file and, if it is a part of a larger collection of files, to the entire superset of 
files. The version resource with a resource ID number of 1 specifies the version of the 
file; the version resource with a resource ID number of 2 specifies the version of the set 
of files. 


Each version resource should contain these elements: 


m Major revision level in binary-coded decimal format. Although the Finder doesn’t 
display it anywhere, you can store this information here; most programming 
environments provide a tool for setting this element. 


m Minor revision level in binary-coded decimal format. Although the Finder doesn’t 
display it anywhere, you can store this information here; most programming 
environments provide a tool for setting this element. 


m Development stage. You can use any of these values or the constants that 
represent them: 


Value Constant Description 
0x20 development Prealpha file 
0x40 alpha Alpha file 
0x60 beta Beta file 
0x80 release Released file 


m Prerelease revision level. This number specifies the version if the software is still 
prerelease. 


m Region code. This identifies the script system for which this version of the software is 
intended. See the chapter “Script Manager” in Inside Macintosh: Text for information 
about the values represented by the various region codes that can be specified here. 


m Version number. This string identifies the version number of the software. When the 
user opens the Views control panel, clicks the Show version box, and then chooses any 
command from the View menu other than by Icon or by Small Icon, the Finder 
window containing this application displays this string. 
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m Version message. This string identifies the version number and either a company 
copyright for a file or a product name for a superset of files. When the user selects this 
file and chooses the Get Info command, the Finder displays this string in the 
information window as follows: 

For a version resource with a resource ID number of 1, this string is displayed in 
the version field of the information window. 

For a version resource with a resource ID number of 2, this string is displayed 
beneath the file’s name next to the file’s icon at the top of the information window. 


Listing 7-9 illustrates the version resources for a graphics application and for the 
document-processing system of which it is a part. Notice that the paint program is 
version 1.0 while the set of files that compose the entire document-processing system 
is version 2.0. 


Listing 7-9 Rez input for a pair of version resources 


resource 'vers' (1, purgeable) { 
0x01, 0x00, release, 0x00, verUS, 
MA SO 
"1.0 (US), © My Company, Inc. 1992" 
}; 
resource 'vers' (2, purgeable) { 
0x02, 0x00, release, 0x00, verUS, 
MZ 0; 
"(for SurfWriter 3.0)" 
}; 


Figure 7-13 illustrates how the Finder displays the information from these resources in 
its information window. 


You can store version resources in any kind of file, not just an application. If your 
application does not contain a version resource with a resource ID number of 1, the 
Finder displays the string from your signature resource as the version information 
in the information window for your application. 


Using Finder Information in the Catalog File 


A catalog file exists on every volume to maintain relationships between the files and 
directories on that volume. (A volume is any storage medium formatted to contain files.) 
Although it’s used mostly by the File Manager, the catalog file also contains information 
used by the Finder. The information for files is listed in file information records (data 
structures of type F Info) and in extended file information records (data structures of 
type FXInfo). The information for directories is listed in directory information (DInfo) 
records and in extended (DXInfo) directory information records. 
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Figure 7-13 The version data in the information window 
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| Locked 





The Finder manipulates the fields in the file information, directory information, and 
extended directory information records; your application shouldn’t have to directly 
check or set any of these fields. 


Normally, your application sets the file type and the creator information in fields of the 
file’s file information record when your application creates a new file; for example, the 
File Manager function FSpCreate (described in Inside Macintosh: Files) takes a creator 
and a file type as parameters. The Finder manipulates the other fields in the file 
information record, which is shown here: 


TYPE FInfo = 








RECORD 
fdType: OSType; {file type} 
fdCreator: OSType; {file creator} 
fdFlags: Integer; {Finder flags} 
fdLocation: Point; {file's location in window} 
fdFldr: Integer; {directory that contains file} 
END; 





After you have created a file, you can use the File Manager function FSpGetFInfo to 
return the file information record, then change the fdType and fdCreator fields by 
using the File Manager function FSpSetFInfo. 


Using the Finder Interface 7-33 


7-34 


CHAPTER 7 


Finder Interface 


You can check the information in this record by calling the File Manager function 
FSpGetFInfo or PBGetCat Info. In particular, you may want to check the file type 

or creator for a file, or you may want to check or set one of your document's Finder flags. 
See “File Information Record” beginning on page 7-47 for a list of all the Finder flags. 
The only Finder flags you might ever want to set are described here: 


m isInvisible. This flag specifies that a file is invisible from the Finder and from the 
Standard File Package dialog boxes. Making a file invisible is generally not 
recommended. Not even temporary files need to be invisible because the Temporary 
Items folder into which they should be written is invisible. The Temporary Items 
folder is described in “Using the System Folder and Its Related Directories” beginning 
on page 7-41. 


m hasBundle. This flag specifies that a file has a bundle resource that associates the file 
with your own icons. When the Finder displays or manipulates a file, it checks the 
file’s hasBund1le bit (also called the bundle bit). If that bit is not set, the Finder 
displays a default icon for that file type. If the hasBund1e bit is set, the Finder checks 
the hasBeenInited bit. If the hasBeenInited bit is set, the Finder uses the 
information in the desktop database to display that file’s icon. If the hasBeenInited 
bit is not set, the Finder installs the information from the bundle resource in the 
desktop database and sets the hasBeenInited bit. Most development environments 
provide a simple tool for setting the bundle bit when you create your application. 





m nameLocked. This flag specifies that a file cannot be renamed from the Finder and 
that the file cannot have customized icons assigned to it by users. 


m isStationery. This flag specifies that a file is a stationery pad. To support 
stationery pads, your application should check this bit for every document passed to 
it by either the Finder or the Standard File Package. (The File Manager functions 
StandardGetFileandCustomGetFile return this flag in the sfFlags field of the 
standard file reply record.) If the isStationery bit is set for a file that a user wants 
to open, your application should copy the template’s contents into a new document 
and open the document in an untitled window. Stationery pads are described in the 
next section. 


m isShared. This flag specifies that a file is an application that multiple users on a 
network can execute simultaneously. 


m hasCustomicon. This flag specifies that a file has a customized icon. “Creating 
Customized Document Icons” beginning on page 7-17 explains how users or your 
application can use customized icons. 


Supporting Stationery Pads 


Stationery pads are special documents that the user creates as templates. Opening 

a stationery pad should not open the document itself; instead, it should open a new 
document with the same contents as the stationery pad. To turn any document into 

a stationery pad, the user selects it, chooses Get Info from the File menu, and clicks 

the Stationery pad checkbox in the information window. The Finder tags a document as 
being a stationery pad by setting the isStationery bit in the file’s Finder flags field. 
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When the user opens a stationery pad from the Finder, the Finder first checks your 
application’s size resource to see if your application supports stationery. The 'SIZE' 
resource tells the Finder and the Process Manager which features your application 
supports and how much memory to allocate when it starts up your application. 
Listing 7-10 illustrates a size resource. 


Listing 7-10 Rez input for a size resource 


resource 'SIZE' (-1, purgeable) { 
reserved, 
accept SuspendResumeEvents, 
reserved, 
canBackground, 
doesActivateOnFGSwitch, 
backgroundAndForeground, 
dontGetFrontClicks, 
ignoreAppDiedEvents, 
is32BitCompatible, 
isHighLevelEventAware, 
localAndRemoteHLEvents, 
isStationeryAware, /*support stationery pads*/ 








dontUseTextEditServices, 
reserved, reserved, reserved, 
kPrefSize * 1024, 

kMinSize * 1024 





hi 
Notice that the twelfth field, isStat ioneryAware, tells the Finder that this application 
supports stationery pads. 


If the isStationeryAware bit is not set in the size resource, the Finder creates a 
new document from the template and prompts the user for a name. The Finder then 
starts up your application as usual, passing it the name of the new document. 


If the isStationeryAware bit is set, as shown in Listing 7-10, the Finder informs your 
application that the user has opened a document and passes your application the name 
of the stationery pad. 


To support stationery, your application should 
m specify the isStationeryAware constant in its size resource 
m always check the isStationery bit of a document before opening it 


Listing 7-11 on page 7-36 illustrates a simple function that takes a file system 
specification record and returns TRUE or FALSE, indicating whether the file is a 
stationery document or not. 
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Listing 7-11 Determining whether a document is a stationery pad 


FUNCTION IsStationeryDoc (myFSSpec: FSSpec): Boolean; 
VAR 








myErr: OSErr; 
myFInfo: Finfo; 
BEGIN 
myErr := FSpGetFInfo(myFSSpec, myFInfo); 








IF myErr = nokrr THEN 


IsStationeryDoc 
ELSE 
IsStationeryDoc 


BTST(myFInfo.fdFlags, isStationery) 





FALSE; 
END; 


The isStationery bit alone identifies whether a document is stationery. If the 
isStationery bit is set for a file that the user wants to open, your application should 
copy the template’s contents into a new document and open the document in an untitled 
window. (For information about opening documents and about the File Manager 
function FSpGet FInfo, see Inside Macintosh: Files.) 


Your application can check the sfFlags field of the standard file reply record to 
determine whether the isStationery bit is set. Unlike the Finder, the Standard File 
Package always passes your application the stationery pad itself, not a copy of it, 
regardless of the setting of the isStationery bit. When the user opens a stationery 
pad from within your application, the Standard File Package checks your application’s 
size resource. If your application does not support stationery, the Standard File Package 
displays an alert box warning the user that the stationery pad itself, not a copy of it, 

is being opened. As you can see, the user can still easily change the template and 
mistakenly write over it by choosing Save without assigning a new name. You can 
prevent this unnecessary user frustration by making your application stationery-aware. 


You can supply the icon to be displayed for stationery pads created from your 
application’s documents by using the resources described in “Creating Icons for the 
Finder” beginning on page 7-11. If you do not supply your own stationery pad icon, the 
Finder uses the default stationery pad icon illustrated in Figure 7-5 on page 7-12. 


In your documentation, tell users to choose the Get Info command to make stationery 
pads. You may also want to give examples of useful stationery pads created with your 
application. For example, if your application supports text and graphics, you may 
provide samples of stationery pads for business letterheads or billing statements. 


Distributing Fonts, Sounds, and Other Movable Resources 


If you create fonts, sounds, keyboard layouts, and script system resource collections, you 
can distribute them in individual, movable resource files. 


Movable resources such as fonts, keyboard layouts, and sounds are represented on the 
screen by icons. To install these resources, the user drags their icons to the System Folder 
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icon. The Finder puts font resources in the Fonts folder, and it puts the other resources 

in the System file. The user can determine which fonts are currently installed by double- 
clicking the System Folder to open it and then double-clicking the Fonts folder. By 
double-clicking the System file so that it opens like a folder, the user can see which other 
movable resources are installed. (For a description of the new organization of the System 
Folder, see “Using the System Folder and Its Related Directories” beginning on 

page 7-41.) 


To make one of these resources visible on the screen, assign it one of the special file types 
defined by the Finder for movable resources. The following list shows the resources that 
can be moved, their assigned file types, and their icons: 


Large black- 
Resource File type and-white icon 
Font so (A 
Keyboard layout "kfil' A 


Script system "efi" 
resource collection 





Sound VS fil 4 


TrueType font MC#il? 


Note 

You or your users can give customized icons to these file types (as 
described in “Creating Customized Document Icons” beginning on 
page 7-17) as long as the files are not installed in the System file 

or in a suitcase file. As soon as users install them in the System file or 
in a suitcase file, the Finder displays them using the icons shown in 
the previous list. Font and TrueType font movable resources retain 
their custom icons when installed in the Fonts folder. 


The user can still store fonts (as well as desk accessories) in files that have suitcase icons, 
which is how they were distributed for installation or saved by the user using the 
Font/DA Mover in versions of system software that preceded System 7. A suitcase file 
that holds desk accessories is of type 'DFIL"', and a suitcase file that holds fonts is of 
type 'FFIL'. All suitcase files have a creator of 'DMOV'. 
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In your documentation, tell users to install fonts, sounds, or script system resource 
collections by dragging their icons to the System Folder icon. A dialog box appears 
asking the user to verify that the resource should be installed in either the Fonts folder 
or the System file. The user clicks OK to accept the installation. The user also has the 
option to click Cancel to prevent the installation. 


Note 

If users drag icons to the open System Folder window instead of to the 
System Folder icon, the Finder copies or moves the files into the System 
Folder directory instead of installing them into either the Fonts folder or 
the System file. 


Providing Balloon Help for Nondocument Icons 


The Finder offers Balloon Help online assistance for users. After the user chooses Show 
Balloons from the Help menu, descriptive help balloons appear when the user moves the 
cursor to an area of the screen (such as a menu, a window control, or a dialog box) that 
has a help resource associated with it. 


The Finder provides default help balloons for application, control panel, and system 
extension icons. You can provide a customized help balloon for your application, control 
panel, or system extension icon by adding an 'hfdr' resource with resource ID —-5696 to 
the resource fork of your application. Figure 7-14 compares the default help balloon with 
a customized help balloon for the SurfWriter application icon. 


Figure 7-14 Default and customized help balloons for application icons 


Default help balloon for Customized help balloon for 
an application icon an application icon 


This is an application—a program Use the Surfwriter word 
with which you can perform 4 processor to create or 
task or create a document. edit the swellest 
Applications include word documents you ever 


processors, graphics programs, wrote on your Macintosh 
database programs, games, and computer. 
spreadsheets. 





es Surfwriter 3.0 
Surfwriter 3.0 


Listing 7-12 shows a Finder help override resource and its associated 'STR ' resource, 
which are used for the customized help balloon shown in Figure 7-14. 


Note 

You cannot override the default help balloon that the Finder uses 

for document icons. 

The chapter “Help Manager” in Inside Macintosh: More Macintosh Toolbox describes in 
detail how to provide Balloon Help for your application icon and for other elements of 
your application. 
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Listing 7-12 Rez input for a help balloon resource for an application icon 


resource 'hfdr' (-5696, purgeable) { /*help for SurfWriter icon*/ 
HelpMgrVersion, hmDefaultOptions, 0, 0, /*header information*/ 
{HMSTRResItem {kIconHelpString} } 

}; 

resource 'STR ' (kIconHelpString, purgeable) {/*help message for app icon*/ 
"Use the SurfWriter word processor to create or edit the " 
"swellest documents you ever wrote on your Macintosh computer." 

}; 


Using Aliases 


The Finder allows the user to create multiple icons to represent a single document or 
other desktop object (such as a disk, a folder, or the Trash). One of the icons represents 
the actual file; the others are aliases that point to the file. An alias is an object that 
represents some other file, directory, or volume. An alias looks like the icon of its target, 
but its name is displayed in a different style. The style depends on the system script; for 
Roman and most other scripts, alias names are displayed in italic. 


To the user, the icons of the actual file and its aliases are functionally identical. Aliases 
give the user more flexibility in organizing files and offer a convenient way to store a 
local copy of a large or dynamic file that resides on a file server. 


Ordinarily, when the user wants to open or print files, your application does not need to 
be concerned with whether they are aliases because both the Finder and the Standard 
File Package resolve aliases before passing them to your application. If the user opens an 
alias that represents a document created by your application, the Finder passes your 
application the name and location of the document itself, not the alias. Similarly, when 
the user opens an alias from within your application, the Standard File Package passes 
your application the name of the target document. 


If your application opens a file or a directory without going through the Finder or the 
Standard File Package (if, for example, it uses preference files or dictionary files), your 
application should always call the ResolveAliasFile function just before opening 
the file. 


As a Finder object, the alias depicts a file called the alias file, which contains a record 
that points to the file, directory, or volume represented by the icon. Alias files are created 
and managed by the user through the Finder. 


Although your application shouldn’t create alias files or change users’ aliases, your 
application can create and use its own alias records for storing identifying information 
about files or directories. An alias record is a data structure that identifies a file, folder, or 
volume. Whenever your application needs to store file or directory information, you can 
record the location and other identifying information in an alias record. The next time 
your application needs the file or directory, you can use the Alias Manager to locate it, 
even if the user has renamed it, copied it, restored it from backup, or moved it. You can 
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also use alias records to identify objects on other volumes, including AppleShare 
volumes. See the chapter “Alias Manager” in Inside Macintosh: Files for details about 
creating and managing information in alias records. 


An alias file contains an alias record, stored as a resource of type 'alis', that points to 
the target of the alias. (The alias target is the file, directory, or volume described by the 
alias record.) The alias file might also contain the target object’s icon descriptions. The 
Finder identifies an alias file by setting the isAlias bit in the file’s Finder flags field (see 
“File Information Record” beginning on page 7-47 for a description of Finder flags). 


An alias file that represents a document typically has the same type and creator as the 
file it represents. However, many Finder objects—such as disks, folders, and the Trash— 
do not have file types. Instead, alias files for these objects are assigned special file 

types, called alias types. Here are the alias types for those objects for which users can 
create aliases: 








Object Alias type Constant 

Apple Menu Items 

folder 'faam' kAppleMenuFolderAliasType 
AppleShare drop folder 'fadr' kDropFolderAliasType 
Application ‘adrp' kApplicationAliasType 
Control Panels folder "fact! kControlPanelFolderAliasType 
Exported 

AppleShare folder "faet' kExportedFolderAliasType 
Extensions folder "faex' kExtensionFolderAliasType 
File server "srvr' kContainerServerAliasType 
Floppy disk "flpy' kContainerFloppyAliasType 
Folder 'fdrp' kContainerFolderAliasType 
Hard disk "hdsk' kContainerHardDiskAliasType 
Mounted 

AppleShare folder 'famn' kMountedFolderAliasType 
Other objects that 

can hold files ‘drop' kContainerAliasType 
Preferences folder "fapf' kPreferencesFolderAliasType 
PrintMonitor 

Documents folder 'fapn' kPrintMonitorDocsFolderAliasType 
Shared 

AppleShare folder 'fash' kSharedFolderAliasType 
Startup Items folder ‘fast! kStartupFolderAliasType 
System Folder 'fasy' kSystemFolderAliasType 

Trash "trsh' kContainerTrashAliasType 


(The Extensions, Preferences, Apple Menu Items, Control Panels, Startup Items, and 
PrintMonitor Documents folders are described in “Using the System Folder and Its 
Related Directories” beginning on page 7-41.) 
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When opening a file without going through the Finder or the Standard File Package, 
you call ResolveAliasFile immediately before opening the file. (The 
ResolveAliasFile function is described in detail on page 7-52.) In Listing 7-13, 
the customized open function MyOpen ensures that the file to be opened is the target 
file and then opens the data fork with the File Manager function FSpOpenDF. 





Listing 7-13 Using the ResolveAliasFile function to open a file 
FUNCTION MyOpen (VAR theSpec: FSSpec; perm: SignedByte; 
VAR fRefNum: Integer): OSErr; 
VAR 
myErr: OSErr; 
targetIsFolder: Boolean; 
wasAliased: Boolean; 
BEGIN 
myErr := ResolveAliasFile(theSpec, TRUE, targetIsFolder, wasAliased) ; 
IF targetIsFolder THEN 
myErr := paramErr {cannot open a folder} 
ELSE IF (myErr <> noErr ) THEN {try to open it} 
myErr := FSpOpenDF (theSpec, perm, fRefNum) ; 
MyOpen := myErr; 
END; 





Using the System Folder and Its Related Directories 


The System Folder is a directory that stores essential system software such as the System 
file, the Finder, and printer drivers. System 7 introduced a new organization for the 
System Folder, which contains a set of new subdirectories to hold related files. The 
Finder uses these subdirectories to facilitate file management for the user. For example, 
by sorting and storing such files as desk accessories, control panels, fonts, preferences 
files, system extensions, and temporary files into separate folders for the user, the Finder 
keeps the top level of the System Folder from being cluttered with dozens, or even 
hundreds, of files. 


The user can easily install and remove fonts, sounds, keyboard layouts, control panels, 
and system extensions by dragging their icons to the System Folder icon. The Finder 
then moves them into the proper subdirectories. When a control panel icon is dragged to 
the System Folder icon, for example, the Finder presents a dialog box that asks the user, 
“Place this control panel into the ‘Control Panels’ folder?” The user accepts by clicking 
the OK button or declines by clicking the Cancel button. 


Note 


If users drag icons to the open System Folder window instead of to 
the System Folder icon, the Finder copies or moves the files into the 
System Folder directory instead of copying or moving them to the 
proper subdirectories. 
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Figure 7-15 shows a user’s view of the new directory organization typically found within 
the System Folder. 


Figure 7-15 The System Folder and related folders 
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Additional related directories are located at the root directory. Notice the Trash window. 
It shows the contents of the Trash directory, which is represented to the user by the Trash 
icon. The Trash directory exists at the root level of the volume. A Macintosh sharing files 
among users in a network environment maintains separate Trash subdirectories within a 
shared Trash directory. That is, the server creates a separate, uniquely named Trash 
subdirectory for every user who opens a volume on a Macintosh server and drags an 
object to the Trash icon. All Trash subdirectories within a shared Trash directory are 
invisible to users. On the desktop, the user sees only the Trash icon of the local 
Macintosh computer. When the user double-clicks the Trash icon, a window reveals the 
names of only those files that the user has thrown away; no distinction is made to the 
user as to which computers any of these files originated on. 


At the root level of the volume, the Finder also maintains a Temporary Items folder 
and a Desktop Folder, both of which are invisible to the user and so don’t appear 
in Figure 7-15. 


Figure 7-15 illustrates the folder organization typically found on single-user systems. Of 
all the related directories shown, your application is likely to use only the Preferences 
folder and the Temporary Items folder. However, you cannot be certain of the location of 
these or any of the other system-related directories. In the future, these system-related 
directories may not be located in the System Folder or in the root directory. 


You can use the FindFolder function (described on page 7-54) to get the path 
information to these directories. Of these directories, the only ones you are ever likely 
to need are Preferences, Temporary Items, and Trash. For example, you might wish to 
check for the existence of a user’s configuration file in Preferences, create a temporary 
file in Temporary Items, or—if your application runs out of storage when trying to save 
a file—check how much storage is taken by items in the Trash directory and report this 
to the user. 
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Your application may freely use these two directories for storing and locating 
important files: 


m Preferences, located in the System Folder, holds preferences files to record local 
configuration settings. Your application can store its preferences file in this directory. 
The active Finder Preferences file is always stored in the Preferences folder. Do not use 
the Preferences folder to hold information that is to be shared by users on more than 
one Macintosh computer on a network. Ensure that your application can always 
operate even if its preferences file has been deleted. 


a Temporary Items, located at the root level of the volume, holds temporary files 
created by applications. The Temporary Items folder is invisible to the user. Your 
application can place its temporary files in this directory. A temporary file should exist 
only as long as your application needs to keep it open. As soon as your application 
closes the file, your application should remove the temporary file. You should also 
ensure that you are assigning a unique name to your temporary file so that you don’t 
write over another application’ file. 


It’s important to bear in mind a few rules about storing your application’s files. First, 
don’t store any files at the top level of the System Folder. Use the Preferences directory 
or one of the other directories described in the following list. 


Second, use the FindFolder function to locate or put files in the right place. Don’t 
assume files are on the same volume as your application; they could be on a different 
local volume, or on a remote volume on the network. 


Third, don’t store any files that multiple users may need to access, such as dictionaries 
and format converters, in the Preferences directory or in any of the directories located in 
the System Folder. Remember that the files in the System Folder are generally accessible 
only to the person who starts up from the System file in that System Folder. 


There are additional directories that either the user or the Finder uses for storing and 
locating important files; these directories are described here. Generally, your application 
should not store files in these directories. 


mu Apple Menu Items, located in the System Folder, holds the standard desk accessories 
plus any other desk accessories, applications, files, folders, or aliases that the user 
wants to display in the Apple menu. Only the user and the Installer should put things 
into the Apple Menu Items folder. 


= Control Panels, located in the System Folder, holds control panels. The Apple Menu 
Items folder holds an alias to the Control Panels folder so that the user can also reach 
the control panels through the Apple menu. Only the user and the Installer should put 
things into the Control Panels folder. 


ma Desktop Folder, which is invisible to users, is located at the root level of the volume. 
The Desktop Folder stores information about the icons that appear on the desktop 
area of the screen. The user controls the contents of the Desktop Folder by arranging 
icons on the screen. What appears on the screen to the user is the union of the contents 
of Desktop Folders for all mounted volumes. 


m Extensions, located in the System Folder, holds extensions—that is, code that is not 
part of the basic system software but that provides system-level services, such as 
printer drivers and system extensions. Files of type 'INIT', previously called startup 
documents, and of type 'appe', also known as background-only applications, are 
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routed by the Finder to this folder. Files of type 'scri' (system extensions for 
script systems) are also routed to this folder. Only the user and the Installer should 
put files into the Extensions folder. 


m Fonts, located in the System Folder on computers using system software version 7.1 
or later, holds fonts. Only the user and the Installer should put fonts into the Fonts 
folder. 


a PrintMonitor Documents, located in the System Folder, holds spooled docu- 
ments waiting to be printed. Only the printing software uses the PrintMonitor 
Documents folder. 


m Rescued Items from volume name, located in the Trash directory, is a directory 
created by the Finder at system startup, restart, or shutdown only when the Finder 
finds items in the Temporary Items folder. Since applications should remove their 
temporary files when they close them, the existence of a file ina Temporary Items 
folder indicates a system crash. When the Finder discovers a file in the Temporary 
Items folder, the Finder creates a Rescued Items from volume name directory that is 
named for the volume on which the Temporary Items folder exists. For example, the 
Finder creates a directory called Rescued Items from Loma Prieta when a file is 
discovered in the Temporary Items folder on a volume named Loma Prieta. The 
Finder then moves the temporary file to that directory so that users can examine the 
file in case they want to recreate their work up to the time of the system crash. When a 
user empties the Trash, all Rescued Items folders disappear. Only the Finder should 
put anything into Rescued Items directories. 


a Startup Items, located in the System Folder, holds applications and desk accessories 
(or their aliases) that the user wants started up every time the Finder starts up. 
Only the user should put things into the Startup Items folder. Note that there is a 
distinction between startup applications that users put in the Startup Items folder 
and system extensions of file type 'INIT' (previously called startup documents), 
which are typically installed in the Extensions folder. 


mu System file, located in the System Folder, contains the basic system software plus 
some system resources, such as sound and keyboard resources. The System file 
behaves like a folder in this regard: although it looks like a suitcase icon, double- 
clicking it opens a window that reveals movable resource files (such as sounds, 
keyboard layouts, and script system resource collections) stored in the System file. 
(“Distributing Fonts, Sounds, and Other Movable Resources” beginning on page 7-36 
describes the resources that can be moved into the System file.) Only the user and the 
Installer should put resources into the System file. 


m Trash, located at the root level of a volume, holds items that the user moves to the 
Trash icon. After opening the Trash icon, the user sees the collection of all items that 
he or she has moved to the Trash icon—that is, the union of all appropriate Trash 
directories from all mounted volumes. A Macintosh set up to share files among users 
in a network environment maintains separate Trash subdirectories for remote users 
within its shared Trash directory. That is, the server creates a separate, uniquely 
named Trash subdirectory for every remote user who opens a volume on a Macintosh 
file server and drags an object to the Trash icon. All Trash subdirectories and the 
shared Trash directory are invisible to users. The Finder empties a Trash directory (or, 
in the case of a file server, a Trash subdirectory) only when the user of that directory 
chooses the Empty Trash command. 
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Although the names of the visible system-related folders vary on different international 
systems, the invisible directories Temporary Items and Desktop Folder keep these names 
on all systems. System software assigns unique names for invisible Trash subdirectories. 


Generally, you should store application-specific files in the folder with your application, 
not in any of these system-related directories. Your application may want to provide 
users with a mechanism to specify a directory in which to look for auxiliary files. For 
example, you could design a customized version of the open file dialog box that allows 
users to specify a path to locations where files are stored. This technique may be useful 
for finding files that are shared by several applications. It’s also possible to track the 
location of files by using the Alias Manager. For details, see the chapter “Alias Manager” 
in Inside Macintosh: Files. 


When you design your application, it’s important to consider the user’s view of the tools 
that you provide. In most cases you'll want to build your application so that the user 
deals with one icon that represents the entire set of abilities your application provides. 
This scheme simplifies the user’s world by restricting the complexity of installing and 
maintaining your product. If you provide optional tools—such as a dictionary and 
thesaurus—that have their own icons, it’s a good idea to allow these tools to work from 
any location in the file system rather than relying on their storage somewhere in the 
System Folder. 


The Desktop Database 


For quick access to the resources it needs, the Finder maintains a central desktop 
database of information about the files and directories on a volume. The Finder 
updates the database when applications are added, moved, renamed, or deleted. 


Normally, your application won’t need to use the information in the desktop database 
or to use Desktop Manager routines to manipulate it. Instead, your application should 
let the Finder manipulate the desktop database and handle such Desktop Manager tasks 
as launching applications when users double-click icons, maintaining user comments 
associated with files, and managing the icons used by applications. 


In case you discover some important need to retrieve information from the desktop 
database or even to change the desktop database from within your application, Desktop 
Manager routines are provided for you to do so. While your application probably won’t 
ever need to use them, for the sake of completeness they are described in Inside 
Macintosh: More Macintosh Toolbox. 


Much of the information in the desktop database comes from the bundle resources 

for applications and other files on the volume. (See “Using Finder Information in the 
Catalog File” beginning on page 7-32 for a discussion on setting the bundle bit of an 
application so that its bundled resources get stored in the desktop database.) The 
desktop database contains all icon definitions and their associated file types. It lists all 
the file types that each application can open and all copies or versions of the application 
that’s listed as the creator of a file. The desktop database also lists the location of each 
application on the disk and any comments that the user has added to the information 
windows for desktop objects. 
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The Finder maintains a desktop database for each volume with a capacity greater than 
2 MB. For most volumes, such as hard disks, the database is stored on the volume itself. 
For read-only volumes—such as some compact discs—that don’t contain their own 
desktop database, the Desktop Manager creates it and stores it in the System Folder of 
the startup drive. 


For compatibility with older versions of system software, the Finder keeps the informa- 
tion for ejectable volumes with a capacity smaller than 2 MB in a resource file instead of 
a database. 


Finder Interface Reference 


This section describes the data structures, routines, and resources that are specific to the 
Finder interface. 


The “Data Structures” section shows the data structures for the file information record, 
the extended file information record, the directory information record, and the extended 
directory information record. The “Routines” section describes the routines for resolving 
alias files and for finding system-related folders. The “Resources” section describes the 
resources you supply for your files so that the Finder can relay information about them 
to your users. 
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A catalog file exists on every volume to maintain relationships between the files and 
directories on that volume. (A volume is any storage medium formatted to contain files.) 
Although it’s used mostly by the File Manager, the catalog file also contains information 
used by the Finder. The information for files is listed in file information records and 
extended file information records; the information for directories is listed in directory 
information records and extended directory information records. 


Normally, your application sets the file type and the creator information in fields of a file 
information record when your application creates a new file. (For a complete discussion 
of the File Manager and the functions available for creating files, see Inside Macintosh: 
Files.) The Finder manipulates the other fields in the file information record. You can 
check the information in this record by calling the File Manager function FSpGetFInfo 
orPBGetCat Info. In particular, you may want to check the file type or creator for a file, 
or you may want to check or set one of your document’s Finder flags. 


The Finder manipulates the fields in the extended file information, directory informa- 
tion, and extended directory information records; your application shouldn’t have to 
directly check or set any of these fields. These data structures are described here for 
completeness. 
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File Information Record 


You typically set a file’s type and creator when you create the file; for example, you pass 
a creator and a file type to the File Manager function FSpCreate as parameters. The 
Finder manipulates the other fields in the file information record, which is a data 
structure of type FInfo. After you have created a file, you can use the File Manager 
function FSpGet F Info to return the file information record, then change the fdType 
and fdCreator fields by using the File Manager function FSpSetFInfo. 


TYPE FInfo = 
RECORD 
fdType: 
fdCreator: 
fdFlags: 
fdLocation: 
fdFldr: 
END; 











Field descriptions 
fdType 


OSType; 
OSType; 
Integer; 
Point; 
Integer; 


{file type} 

{file creator} 

{Finder flags} 

{file's location in window} 


{window that contains file} 


File type. For a discussion of file types, see “Giving a Signature to 


Your Application and a Creator and a File Type to Your Documents” 


beginning on page 7-8. 


fdCreator 


The signature of the application that created the file. For a 


discussion about creators, see “Giving a Signature to Your 
Application and a Creator and a File Type to Your Documents” 


beginning on page 7-8. 


fdFlags 


Finder flags. There are only a few flags that your application might 


ever need to set; these are described in “Using Finder Information 
in the Catalog File” beginning on page 7-32. All of the Finder flags 
are listed here for completeness. 


Flag name 


isAlias 


isInvisible 


hasBundle 





nameLocked 


isStationery 
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Bit 
number 
15 


14 


13 


12 


11 


Description 
For a file, this bit indicates that the file 


is an alias file. For directories, this bit is 
reserved—in which case, set to 0. 


The file or directory is invisible from the 
Finder and from the Standard File Package 
dialog boxes. 


For a file, this bit indicates that the file 
contains a bundle resource. For directories, 
this bit is reserved—in which case, set to 0. 


The file or directory can’t be renamed from 
the Finder, and the icon cannot be changed. 


For a file, this bit indicates that the file is a 
stationery pad. For directories, this bit is 
reserved—in which case, set to 0. 
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Bit 
Flag name number 
hasCustomIcon 10 
Reserved 
hasBeenInited 
hasNoINITS 7 
isShared 6 
requiresSwitchLaunch 5 
colorReserved 4 
color 1-3 
isOnDesk 0 


Description 


The file or directory contains a 
customized icon. 


Reserved; set to 0. 


The Finder has recorded information from 
the file’s bundle resource into the desktop 
database and given the file or folder a 
position on the desktop. 


The file contains no 'INIT' resources; set 
to 0. Reserved for directories; set to 0. 


The file is an application that can be 
executed by multiple users simultaneously. 
Defined only for applications; otherwise, set 
to 0. 


Unused and reserved in System 7; set to 0. 
Unused and reserved in System 7; set to 0. 
Three bits of color coding. 


Unused and reserved in System 7; set to 0. 


You can use these constants as masks for these flags: 


CONST 
fHasBundle 


fInvisible 
kIsOnDesk = 


kColor = 


kIsShared = 


kHasBeenInited 


kHasCustomIcon 


kIsStationery 


kNameLocked = 


kHasBundle 
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8192; {set if file has a bundle } 
{ resource} 

16384; {set if icon is invisible} 

$1; {unused and reserved in } 


{ System 7} 


SE; {three bits of color } 
{ coding} 

$40; {file can be executed by } 
{ multiple users } 
{ simultaneously} 

$100; {file info is in desktop } 
{ database} 

$400; {file or directory has a } 
{ customized icon} 

$800; {file is a stationery pad} 


$1000; {file or directory can't } 


{ be renamed from Finder, } 
{ and icon can't be } 
{ changed} 


$2000; {file has bundle resource} 
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kIsInvisible= $4000; {file or directory is } 
{ invisible from Finder & } 
{ from Standard File } 
{ Package dialog boxes} 
kIsAlias = $8000; {file is an alias file} 
fdLocation The location—specified in coordinates local to the window—of the 


file’s icon within its window. 


fdFldr The window in which the file’s icon appears; this information is 
meaningful only to the Finder. 


Extended File Information Record 


The Finder manipulates the fields in the extended file information records, which are 
data structures of type FXInfo; your application shouldn’t have to check or set any of 





these fields directly. 
TYPE FXInfo = 
RECORD 
fdiIconID: Integer; {icon ID} 
fdUnused: ARRAY[1..3] OF Integer; 

{unused but reserved 6 bytes} 
fdScript: SignedByte; {script flag and code} 
fdxFlags: SignedByte; {reserved} 
fdComment: Integer; {comment ID} 
fdPutAway: LongInt; {home directory ID} 

END; 
Field descriptions 
fdIconID An ID number for the file’s icon; the numbers that identify icons are 
assigned by the Finder. 
fdUnused Reserved. 
fdScript The script system for displaying the file’s name. Ordinarily, the 


Finder (and the Standard File Package) displays the names of all 
desktop objects in the system script, which depends on the 
region-specific configuration of the system. The high bit of the byte 
in the fdScript field is set by default to 0, which causes the Finder 
to display the filename in the current system script. If the high bit is 
set to 1, the Finder (and the Standard File Package) displays the 
filename and directory name in the script whose code is recorded in 
the remaining 7 bits. 

fdxFlags Reserved. 

f£dComment An ID number for the comment that is displayed in the information 
window when the user selects a file and chooses the Get Info 
command from the File menu. The numbers that identify comments 
are assigned by the Finder. 

fdPutAway If the user moves the file onto the desktop, the directory ID of the 
folder from which the user moves the file. 
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Directory Information Record 


The Finder manipulates the fields in the directory information record, which is a data 
structure of type DInfo. Your application shouldn’t have to check or set any of these 
fields directly. 


TYPE DInfo = 





RECORD 
frRect: Rect; {folder's window rectangle} 
frFlags: Integer; {flags} 
frLocation: Point; {folder's location in window} 
frView: Integer; {folder's view} 

END; 


Field descriptions 


frRect The rectangle for the window that the Finder displays when the 
user opens the folder. 

frFlags Reserved. 

frLocation Location of the folder in the parent window. 

frView The manner in which folders are displayed; this is set by the user 


with commands from the View menu of the Finder. 


Extended Directory Information Record 


The Finder manipulates the fields in the extended directory information records, which 
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are data structures of type DXInfo; your application shouldn’t have to check or set any 
of these fields directly. 


TYPE DXInfo = 














RECORD 
frScroll: Point; {scroll position} 
frOpenChain: LongInt; {directory ID chain of open } 
{ folders} 
£rSeript: SignedByte; {script flag and code} 
frxXFlags: SignedByte; {reserved} 
frComment: Integer; {comment ID} 
frPutAway: LongInt; {home directory ID} 
END; 
Field descriptions 
frScroll Scroll position within the Finder window. The Finder does not 


necessarily save this position immediately upon user action. 
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frOpenChain Chain of directory IDs for open folders. The Finder numbers 
directory IDs. The Finder does not necessarily save this information 
immediately upon user action. 


frScript The script system for displaying the folder’s name. Ordinarily, the 
Finder (and the Standard File Package) displays the names of all 
desktop objects in the current system script, which depends on the 
region-specific configuration of the system. The high bit of the byte 
in the fdScript field is set by default to 0, which causes the Finder 
to display the folder’s name in the current system script. If the high 
bit is set to 1, the Finder (and the Standard File Package) displays 
the filename and directory name in the script whose code is 
recorded in the remaining 7 bits. However, as of system software 
version 7.1, the Window Manager and Dialog Manager do not 
support multiple simultaneous scripts, so the system script is 
always used for displaying filenames and directory names in dialog 
boxes, window titles, and other user interface elements used by the 
Finder. Therefore, until the system software’s script capability is 
fully implemented, you should treat this field as reserved. 

frXFlags Reserved. 

frComment An ID number for the comment that is displayed in the information 
window when the user selects a folder and chooses the Get Info 
command from the File menu. The numbers that identify comments 
are assigned by the Finder. 

frPutAway If the user moves the folder onto the desktop, the directory ID of the 
folder from which the user moves it. 


Routines 
This section describes the routines your application can use to resolve alias files if it 
bypasses the Finder when manipulating documents and to find system-related folders 
if your application needs to determine where they are located. 

Resolving Alias Files 


Ordinarily, when the user wants to open or print files, your application does not need to 
be concerned with whether they are aliases because the Finder resolves aliases before 
passing them to your application. If the user opens an alias that represents a document 
created by your application, the Finder passes your application the name and location of 
the document itself, not the alias. (Similarly, when the user opens an alias from within 
your application, the Standard File Package passes your application the name of the 
target document.) If your application bypasses the Finder when manipulating 
documents, it should check for and resolve aliases itself by using the Alias Manager 
function ResolveAliasFile, which is described here for completeness. 
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ResolveAliasFile 


DESCRIPTION 
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If your application bypasses the Finder when manipulating documents, it should check 
for and resolve aliases itself by using the ResolveAliasFile function. 


FUNCTION ResolveAliasFile (VAR theSpec: FSSpec; 
resolveAliasChains: Boolean; 
VAR targetIsFolder: Boolean; 
VAR wasAliased: Boolean): OSErr; 





theSpec A file system specification record for the file or directory you plan to open. 


resolveAliasChains 
A Boolean value. Set this parameter to TRUE if you want 
ResolveAliasFile to resolve all aliases in a chain, stopping only when 
it reaches the target file. Set this parameter to FALSE if you want to 
resolve only one alias file, even if the target is another alias file. 


targetIsFolder 
A return parameter only. The ResolveAliasFile function returns 
TRUE in this parameter if the file specification record in the parameter 
theSpec points to a directory or a volume; otherwise, 
ResolveAliasFile returns FALSE in this parameter. 


wasAliased 
A return parameter only. The ResolveAliasFile function returns 
TRUE in this parameter if the file specification record in the parameter 
theSpec points to an alias; otherwise, ResolveAliasFile returns 
FALSE in this parameter. 








The ResolveAliasFile function returns in the parameter theSpec the name and 
location of the target file that you initially pass in the parameter theSpec. 


The ResolveAliasFile function first checks the catalog file for the file or directory 
specified in the parameter theSpec to determine whether it is an alias and whether it is 
a file or a directory. If the object is not an alias, ResolveAliasFile leaves theSpec 
unchanged, sets the target IsFolder parameter to TRUE for a directory or volume and 
FALSE for a file, sets wasAliased to FALSE, and returns noErr. If the object is an alias, 
ResolveAliasFile resolves it, places the target in the parameter theSpec, and sets 
the wasAliased flag to TRUE. 














When ResolveAliasFile finds the specified volume and parent directory but fails to 
find the target file or directory in that location, ResolveAliasFile returns a result 
code of fnfErr and fills in the parameter theSpec with a complete file system 
specification record describing the target (that is, its volume reference number, parent 
directory ID, and filename or folder name). The file system specification record is valid, 
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although the object it describes does not exist. This information is intended as a “hint” 
that lets you explore possible solutions to the resolution failure. You can, for example, 
use the file system specification record to create a replacement for a missing file with the 
File Manager function FSpCreate. 


If ResolveAliasFile receives an error code while resolving an alias, it leaves the 
input parameters as they are and exits, returning an error code. In addition to any of 


these result codes, ResolveAliasFile can also return any Resource Manager or File 
Manager errors. 


SPECIAL CONSIDERATIONS 


Before calling the ResolveAliasFile function, you should make sure that it is 
available by using the Gestalt function with the gestaltAliasMgrAttr selector. 





RESULT CODES 
noErr 0 No error 
nsvErr -35 Volume not found 
fnfErr 43 Target not found, but volume and parent directory 
found, and theSpec parameter contains a valid 
file system specification record 
dirNFErr -120 Parent directory not found 
SEE ALSO 


Listing 7-13 on page 7-41 illustrates how to use ResolveAliasFile froman 
application’s own MyOpen function. The file system specification record is described in 
Inside Macintosh: Files. Aliases and other Alias Manager and File Manager routines 

are also described in greater detail in Inside Macintosh: Files. The Gestalt function is 
described in the chapter “Gestalt Manager” in Inside Macintosh: Operating System Utilities. 


Finding Directories 


You can use the FindFolder function to get the path information you need to gain 
access to the system-related directories described in “Using the System Folder and Its 
Related Directories” beginning on page 7-41. Those you’re most likely to want to access 
are Preferences, Temporary Items, and Trash. For example, you might wish to check for 
the existence of a user’s configuration file in Preferences, create a temporary file in 
Temporary Items, or—if your application runs out of disk storage when trying to save a 
file—check how much disk storage is taken by items in the Trash directory and report 
this to the user. 
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To get the path information to gain access to the system-related directories, use the 
FindFolder function. 


FUNCTION FindFolder (vRefNum: Integer; folderType: OSType; 
createFolder: Boolean; 
VAR foundVRefNum: Integer; 
VAR foundDirID: LongInt): OSErr; 


vRefNum The volume reference number (or the constant kOnSystemDisk for the 
startup disk) of the volume on which you want to locate a directory. 


folderType 
A four-character folder type, or a constant that represents the type, for the 
directory you want to find. The constants and the four-character folder 
types they represent are listed here: 





CONST 
kAppleMenuFolderType 

= 'amnu'; {Apple Menu Items} 
kControlPanelFolderType 

= “Cer ls {Control Panels} 
kDesktopFolderType = 'desk'; {Desktop Folder} 
kExtensionFolderType 

= 'extn'; {Extensions} 
kFontsFolderType = 'font'; {Fonts folder} 
kPreferencesFolderType 

= 'pref'; {Preferences } 


kPrintMonitorDocsFolderType 
= 'prnt'; {PrintMonitor } 
{ Documents} 





kStartupFolderType = 'strt'; {Startup Items} 
kSystemFolderType = 'macs'; {System Folder} 
kTemporaryFolderType 

= 'temp'; {Temporary Items} 
kTrashFolderType = 'trsh'; {single-user Trash} 


kWhereToEmptyTrashFolderType 
= 'empt'; {shared Trash on net} 


createFolder 
Pass the constant kCreateFolder in this parameter to create a directory 
if it does not already exist; otherwise, pass the constant 
kDontCreateFolder. 
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foundVvRefNum 
The volume reference number, returned by FindFolder, for the volume 
containing the directory you specify in the folderType parameter. 
foundDirID 
The directory ID number, returned by FindFolder, for the directory you 
specify in the folderType parameter. 


For the folder type on the particular volume (specified, respectively, in the folderType 
and vRefNum parameters), the FindFolder function returns the directory’s volume 
reference number in the foundVRefNum parameter and its directory ID in the 
foundDirID parameter. 


The specified folder used for a given volume might be located on a different volume in 
future versions of system software; therefore, do not assume the volume that you 
specify in vRefNum and the volume returned in foundVRefNum will be the same. 


Specify a volume reference number (or the constant kOnSystemDisk for the startup 
disk) in the vRefNum parameter. 


Specify a four-character folder type—or the constant that represents it—in the 
folderType parameter. Use the kTrashFolderType constant to locate the current 
user’s Trash directory for a given volume—even one located on a file server. On a file 
server, you can use the kWhereToEmptyTrashFolderType constant to locate the 
parent directory of all logged-on users’ Trash subdirectories. 


Use the constant kCreateFolder in the createFolder parameter to tell 
FindFolder to create a directory if it does not already exist; otherwise, use the constant 
kDontCreateFolder. Directories inside the System Folder are created only if the 
System Folder directory exists. The FindFolder function will not create a System 
Folder directory even if you specify the kCreateFolder constant in the 
createFolder parameter 


The FindFolder function returns a nonzero result code if the folder isn’t found, 
and it can also return other file system errors reported by the File Manager or 
Memory Manager. 


SPECIAL CONSIDERATIONS 


The Finder identifies the subdirectories of the System Folder, and their folder types, in a 
resource of type 'f1d#"' located in the System file. Do not modify or rely on the contents 
of the 'f£ld#' resource in the System file; use only the FindFolder function to find the 
appropriate directories. 


To determine the availability of the FindFolder function, use the Gestalt function 
with the Gestalt selector gestaltFindFolderAttr. Test the bit field indicated by the 
gestaltFindFolderPresent constant in the response parameter. If the bit is set, then 
the FindFolder function is present. 


CONST gestaltFindFolderPresent = 0; {if this bit is set, } 
{ FindFolder is present} 
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Err 0 No error 

fErr —43 Type not found in '£1d#' resource, or disk doesn’t 
have System Folder support or System Folder in volume 
header, or disk does not have desktop database support 
for Desktop Folder—in all cases, folder not found 

pFNErr —48 File found instead of folder 





The system-related directories located by the FindFolder function are described in 
“Using the System Folder and Its Related Directories” beginning on page 7-41. 


This section describes the resources you supply for your files so that the Finder can use 
your files and relay information about them to your users. These resources are 


the signature resource—defined using a string ('STR ') resource—which the Finder 
uses to identify and start up your application when a user double-clicks documents 
created by your application 


the set of resources (icon list resource, small icon list resource, large 4-bit color icon 
resource, small 4-bit color icon resource, large 8-bit color icon resource, and small 8-bit 
color icon resource) that visually represent your application and any documents it 
creates, and two related resources, the icon ('ICON') resource and the color icon 
('cicn') resource 


the file reference ('FREF') resource, which links icons with the files types they 
represent and which allows users to launch your application by dragging document 
icons to your application icon 





a bundle ('BNDL') resource, which groups together your application’s signature, icon 
list resource, and file reference resources 


a missing-application name string—that is, a string ('STR ') resource—for your 
application’s documents in order to display the name of your application if the user 
tries to open or print a document created by your application when your application 
is missing 

an application-missing message string—that is, a string ('STR_ ') resource—in your 
application’s documents in order to explain why the user can’t open or print certain 
documents used by your application 


the version ('vers ') resource, so that users can easily find out the version of a file 
and, if applicable, the version of the superset of files to which the single file belongs 





For information about using the 'SIZE' resource to support stationery pads, see 
“Supporting Stationery Pads” beginning on page 7-34. 


This section describes the structures of these resources after they are compiled by the Rez 
resource compiler, available from APDA. If you are interested in creating the Rez input 
files for these resources, see instead “Using the Finder Interface” beginning on page 7-6 
for detailed information. 
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The Signature Resource 


Every application that creates documents should define a signature resource, so that the 
Finder can identify and start up the application when a user double-clicks documents 
created by the application. A signature resource is typically defined to be a string 
resource (that is, a resource of type 'STR ') that is given a unique four-character 
signature as its resource type. For example, an application with the signature of WAVE 
would use a string resource to define its signature resource as a resource of type 'WAVE'. 
The signature resource should have a resource ID number of 0. 





To ensure uniqueness, developers must register their applications’ four-character 
signatures with Apple Computer, Inc., at Macintosh Developer Technical Support. 


This section describes the structure of a signature resource defined to be of type 'STR ' 
after it’s compiled by the Rez resource compiler. The format of a Rez input file for a 
signature resource differs from its compiled output form. If you are concerned only with 
creating a signature resource, see “Giving a Signature to Your Application and a Creator 
and a File Type to Your Documents” beginning on page 7-8. 


If you examine a compiled version of a signature resource, as shown in Figure 7-16, you 
find that it contains a Pascal string that specifies the name, version number, and release 
date of the application. 


Figure 7-16 Structure of a signature resource compiled as a string ('STR ') resource 


Ue gee: sagen eee byppe ae ee SR escerce |= Byles 


7 i 
: i 
: i 
i 
: Bane rension run beer, and rekezeet date of applica don 1 te 256 FH 
; E 

a 


Wasa as aaa asna aaa anaaanasananaasnasaaasasnaaaaansanaasnanaaasasaaaanaaa 


If an application does not provide specific version information through a version 
resource (described in “Providing Version Resources” beginning on page 7-31), the 
Finder displays the string stored in the signature resource when the user selects the 
application and chooses Get Info from the File menu. 


The Icon List Resource 


An icon list resource is one of several icon resources that you create to represent visually 
for the user your application or one of the document types it creates. An icon list 
resource is a resource with the resource type 'ICN#'. Allicon list resources must be 
marked purgeable, and they must have resource IDs greater than 128. 


When the user chooses by Icon from the View menu, the Finder displays the black-and- 

white icon specified in this resource in windows if either the user has a black-and-white 

monitor or your application has not defined any resources for color icons; otherwise, the 
Finder displays a color version of the icon. 
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An icon list resource is defined to be an array of two items of type String [128]; each 
bit in the first array represents a pixel in the 32-by-32 pixel icon, and each bit in the 
second array represents a pixel in the 32-by-32 pixel mask. You can use a high-level tool 
such as the ResEdit application, which is available through APDA, to create icon list 
resources. You can then use the DeRez decompiler to convert your icon list resources into 
Rez input when necessary. See “Creating Icons for the Finder” beginning on page 7-11 
for additional information about creating icon list resources and other resources for 
representing files to users. 


An icon list resource defines one icon, which the Finder uses to display the file it 
represents. If you examine the compiled version of an icon list resource, as represented 
in Figure 7-17, you find that it contains the following elements: 


m The 32-by-32 pixel black-and-white icon. 


m The 32-by-32 pixel black icon mask, which shows the area covered by the black-and- 
white icon and any 32-by-32 pixel color versions of the icon. The Finder uses the mask 
to crop the icon’s outline into whatever background color or pattern is on the desktop. 
The Finder then draws the black-and-white icon specified in this resource—or the 
color icons specified in large 4-bit color icon resources or large 8-bit color icon 
resources—into this shape. 


Figure 7-17 Structure of a compiled icon list ('ICN#') resource 
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To create 16-by-16 pixel and color versions of the icon defined in an icon list resource 
(thereby supplying an entire icon family), your application must also create the 
following resources: a small icon list resource, a large 4-bit color icon resource, a small 
4-bit color icon resource, a large 8-bit color icon resource, and a small 8-bit color icon 
resource. Their compiled formats are described in the next several sections; guidelines 
for creating them are provided in “Creating Icons for the Finder” beginning on page 7-11. 


The Small Icon List Resource 


7-58 


A small icon list resource is one of several resources that you provide for an icon 
family. A small icon list resource is a resource with the resource type 'ics#'. A small 
icon list resource must be marked purgeable, and it must have the same resource 

ID as the icon list resource that represents the file that the small icon list resource 

also represents. 
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When the user chooses by Small Icon from the View menu, the Finder displays the 

small black-and-white icon specified in this resource in windows if either the user has a 
black-and-white monitor or the application has not defined any resources for color icons; 
otherwise, a color version of the icon is displayed. Similarly, the small black-and-white 
icon or its color version appears in the Application menu after the user launches the 
application and in the Apple menu if the user places the application or an alias to it in 
the Apple Menu Items folder. 


A small icon list resource is defined to be an array of two items of type String[32]; 
each bit in the first array represents a pixel in the 16-by-16 pixel icon, and each bit in the 
second array represents a pixel in the 16-by-16 pixel mask. You can use a high-level tool 
such as the ResEdit application to create small icon list resources. You can then use the 
DeRez decompiler to convert your small icon list resources into Rez input when 
necessary. See “Creating Icons for the Finder” beginning on page 7-11 for information 
about creating small icon list resources and other resources for representing files to users. 


A small icon list resource defines one icon, which the Finder uses to display the file it 
represents. If you examine the compiled version of a small icon list resource, as 
represented in Figure 7-18, you find that it contains the following elements: 


a The 16-by-16 pixel black-and-white icon for display on the desktop. 


m The 16-by-16 pixel black icon mask, which shows the area covered by the icon. The 
Finder uses the mask to crop the icon’s outline into whatever background color or 
pattern is on the desktop. The Finder then draws the black-and-white icon specified 
in this resource—or the color icons specified in the small 4-bit color icon resource or 
the small 8-bit color icon resource—into this shape. 


The format for the compiled icon list resource is described on page 7-57; the format 
for the compiled small 4-bit color icon resource is described on page 7-60; and the 
format for the compiled small 8-bit color icon resource is described on page 7-62. 


Figure 7-18 Structure of a compiled small icon list ('ics#') resource 
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The Large 4-Bit Color Icon Resource 


A large 4-bit color icon resource is one of several resources that you provide for an icon 
family. A large 4-bit color icon resource is a resource with the resource type 'icl4'.A 
large 4-bit color icon resource must be marked purgeable, and it must have the same 
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resource ID as the icon list resource that represents the file that the large 4-bit color icon 
resource also represents. 


When the user chooses by Icon from the View menu, the Finder displays the large 4-bit 
color icon specified in this resource in windows if the user has a monitor displaying 

4 bits of color data per pixel. Similarly, the large 4-bit color icon appears in the 
Application menu after the user launches the application and in the Apple menu if the 
user places the application or an alias to it in the Apple Menu Items folder. 


A large 4-bit color icon resource is defined to be of type String [512]; every 4 bits in 
the string represent a pixel in the 32-by-32 pixel icon. You can use a high-level tool such 
as the ResEdit application to create large 4-bit color icon resources. You can then use the 
DeRez decompiler to convert your large 4-bit color icon resources into Rez input when 
necessary. See “Creating Icons for the Finder” beginning on page 7-11 for information 
about creating resources for visually representing files. 


A large 4-bit color icon resource defines one icon, which the Finder uses to display the 
file it represents. If you examine the compiled version of a large 4-bit color icon resource, 
as represented in Figure 7-18, you find that it contains only the 32-by-32 pixel 4-bit color 
icon for display by the Finder. This resource does not specify a mask for the icon; 
instead, the Finder uses the mask specified for the icon list resource with the same 
resource ID number as this resource. 


Figure 7-19 Structure of a compiled large 4-bit color icon ('ic14") resource 





The format for the compiled icon list resource is described on page 7-57. 


The Small 4-Bit Color Icon Resource 
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A small 4-bit color icon resource is one of several resources that you provide for an icon 
family. A small 4-bit color icon resource is a resource with the resource type 'ics4'.A 
small 4-bit color icon resource must be marked purgeable, and it must have the same 
resource ID as the icon list resource that represents the file that the small 4-bit color icon 
resource also represents. 


When the user chooses by Small Icon from the View menu, the Finder displays the small 
4-bit color icon specified in this resource in windows if the user has a monitor displaying 
4 bits of color data per pixel. Similarly, the small 4-bit color icon appears in the 
Application menu after the user launches the application and in the Apple menu if the 
user places the application or an alias to it in the Apple Menu Items folder. 
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A small 4-bit color icon resource is defined to be of type String [128]; every 4 bits in 
the string represent a pixel in the 16-by-16 pixel icon. You can use a high-level tool such 
as the ResEdit application to create small 4-bit color icon resources. You can then use the 
DeRez decompiler to convert your small 4-bit color icon resources into Rez input when 
necessary. See “Creating Icons for the Finder” beginning on page 7-11 for information 
about creating resources for representing files to users. 


A small 4-bit color icon resource defines one icon, which the Finder uses to display the 
file it represents. If you examine the compiled version of a small 4-bit color icon resource, 
as represented in Figure 7-18, you find that it contains only the 16-by-16 pixel 4-bit color 
icon for display by the Finder. This resource does not specify a mask for the icon; 
instead, the Finder uses the mask specified for the small icon list resource with the same 
resource ID number as this resource. 


Figure 7-20 Structure of a compiled small 4-bit color icon ('ics4"') resource 





The format for the compiled icon list resource is described on page 7-57. The format for 
the compiled small icon list resource is described on page 7-58. 


The Large 8-Bit Color Icon Resource 


A large 8-bit color icon resource is one of several resources that you provide for an icon 
family. A large 8-bit color icon resource is a resource with the resource type 'icl8'. 
A large 8-bit color icon resource must be marked purgeable, and it must have the same 
resource ID as the icon list resource that represents the file that the large 8-bit color 
icon resource also represents. 


When the user chooses by Icon from the View menu, the Finder displays the large 8-bit 
color icon specified in this resource in windows if the user has a monitor displaying 

8 bits of color data per pixel. Similarly, the large 8-bit color icon appears in the 
Application menu after the user launches the application and in the Apple menu if the 
user places the application or an alias to it in the Apple Menu Items folder. 


A large 8-bit color icon resource is defined to be of type String [1024]; every byte in 
the string represents a pixel in the 32-by-32 pixel icon. You can use a high-level tool such 
as the ResEdit application to create large 8-bit color icon resources. You can then use the 
DeRez decompiler to convert your large 8-bit color icon resources into Rez input when 
necessary. See “Creating Icons for the Finder” beginning on page 7-11 for information 
about creating resources for visually representing files. 
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A large 8-bit color icon resource defines one icon, which the Finder uses to display the 
file it represents. If you examine the compiled version of a large 8-bit color icon resource, 
as represented in Figure 7-21, you find that it contains only the 32-by-32 pixel 8-bit color 
icon for display by the Finder. This resource does not specify a mask for the icon; 
instead, the Finder uses the mask specified for the icon list resource with the same 
resource ID number as this resource. 


The format for the compiled icon list resource is described on page 7-57. 


Figure 7-21 Structure of a compiled large 8-bit color icon ('ic18") resource 





The Small 8-Bit Color Icon Resource 
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A small 8-bit color icon resource is one of several resources that you provide for an icon 
family. A small 8-bit color icon resource is a resource with the resource type 'ics8'.A 
small 8-bit color icon resource must be marked purgeable, and it must have the same 
resource ID as the icon list resource that represents the file that the small 8-bit color icon 
resource also represents. 


When the user chooses by Small Icon from the View menu, the Finder displays the small 
8-bit color icon specified in this resource in windows if the user has a monitor displaying 
8 bits of color data per pixel. Similarly, the small 8-bit color icon appears in the 
Application menu after the user launches the application and in the Apple menu if the 
user places the application or an alias to it in the Apple Menu Items folder. 


A small 8-bit color icon resource is defined to be of type String [256]; every byte in the 
string represents a pixel in the 16-by-16 pixel icon. You can use a high-level tool such as 
the ResEdit application to create small 8-bit color icon resources. You can then use the 
DeRez decompiler to convert your small 8-bit color icon resources into Rez input when 
necessary. See “Creating Icons for the Finder” beginning on page 7-11 for information 
about creating resources for visually representing files. 


A small 8-bit color icon resource defines one icon, which the Finder uses to display the 
file it represents. If you examine the compiled version of a small 8-bit color icon resource, 
as represented in Figure 7-22, you find that it contains only the 16-by-16 pixel 8-bit color 
icon for display by the Finder. This resource does not specify a mask for the icon; 
instead, the Finder uses the mask specified for the small icon list resource with the same 
resource ID number as this resource. 
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Figure 7-22 Structure of a compiled small 8-bit color icon ('ics8') resource 





The format for the compiled icon list resource is described on page 7-57. The format for 
the compiled small icon list resource is described on page 7-58. 


The Icon Resource 


When you want to display a 32-by-32 pixel black-and-white icon within some element of 
your application (such as within a menu, an alert box, or a dialog box), you can create an 
icon resource. An icon resource is a resource with the resource type 'ICON'. All icon 
resources must be marked purgeable, and they must have resource IDs greater than 128. 


Using icon resources, you can create icons similar to the ones the Finder uses to display 
your application’s files on the desktop; however, unlike the resource types previously 
described in this section, the Finder does not use or display any resources that you create 
of type 'ICON'. Instead, your application uses icon resources of type 'ICON' to display 
icons from within your application. Icon resources are described here for completeness 
and to mitigate the confusion that sometimes arises concerning icon (' ICON") resources 
(which your application creates for its own use), icon list ('ICN#"') resources, and the 
other previously described resources necessary for defining an icon family (which your 
application creates for the Finder’s use). 


See “Creating Icons for the Finder” beginning on page 7-11 for additional information 
about creating icon list resources and other resources for representing files to users. 


Generally, you use icon resources in menus and dialog boxes, as described in the 
chapters “Menu Manager” and “Dialog Manager” in this book. If you provide a color 
icon ('cicn') resource with the same resource ID as the icon resource, the Menu 
Manager and the Dialog Manager display the color icons instead of the black-and-white 
icons for users with color monitors. (For example, the color alert box in Plate 2 specifies a 
resource of type 'cicn"' for the color icon in the upper-left corner of the alert box.) 


An icon resource is defined to be of type String [128]; each bit represents a pixel in the 
32-by-32 pixel icon. As illustrated in Figure 7-23 on the next page, an icon resource 
resembles an icon list resource without the array that specifies the icon’s mask. You can 
use a high-level tool such as the ResEdit application to create icon resources. You can 
then use the DeRez decompiler to convert your icon resources into Rez input when 
necessary. 
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Figure 7-23 Structure of a compiled icon ('ICON') resource 
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The Color Icon Resource 


When you want to display a color icon within some element of your application (such as 
within a menu, an alert box, or a dialog box), you can create a color icon resource. A 
color icon resource is a resource with the resource type 'cicn'. All color icon resources 
must be marked purgeable, and they must have resource IDs greater than 128. 


Using color icon resources, you can create icons similar to the ones the Finder uses to 
display your application’s files on the desktop; however, the Finder does not use or 
display any resources that you create of type 'cicn'. Instead, your application uses 
icon resources of type 'cicn' to display icons from within your application. Color icon 
resources (that is, those of resource type 'cicn') are mentioned here to mitigate the 
confusion that sometimes arises concerning color icon resources (which your application 
creates for its own use) and the small and large 4-bit and 8-bit color icon resources (types 
"ics4', 'icl4', 'ics8',and 'icl18") necessary to define an icon family (which your 
application creates for the Finder’s use). 


See “Creating Icons for the Finder” beginning on page 7-11 for information about 
creating an icon family that includes color icons for representing files to users. 


Generally, you use color icon resources in menus, alert boxes, and dialog boxes, as 
described in the chapters “Menu Manager” and “Dialog Manager” in this book. If you 
provide a color icon ('cicn') resource with the same resource ID as an icon resource 
(described on page 7-63), the Menu Manager and the Dialog Manager display the color 
icon instead of the black-and-white icon for users with color monitors. You can use a 
high-level tool such as the ResEdit application to create color icon resources. You can 
then use the DeRez decompiler to convert your color icon resources into Rez input when 
necessary. (For example, the color alert box in Plate 2 specifies a resource of type 'cicn' 
for the color icon in the upper-left corner of the alert box.) 


See Inside Macintosh: Imaging for more information about color icon resources. 


The File Reference Resource 
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To link icons with the files types they represent and to allow users to launch your 
application by dragging document icons to your application icon, create a file reference 
resource for every icon list resource you create. A file reference resource is a resource 
with the resource type 'FREF '. All file reference resources must have resource IDs 
greater than 128, and each must be marked purgeable. 
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This section describes the structure of a file reference resource after it is compiled by the 
Rez resource compiler. The format of a Rez input file for a file reference resource differs 
from its compiled output form. If you are concerned only with creating a file reference 
resource, see “Creating File Reference Resources” beginning on page 7-18. 


If you examine a compiled version of a file reference resource, as illustrated in 
Figure 7-24, you find that it contains the following elements: 


m File type. This is the four-character code that identifies the type of file represented by 
this resource. File types are described in “Giving a Signature to Your Application and 
a Creator and a File Type to Your Documents” beginning on page 7-8. 


m Local ID. The Finder uses this number to map the file type specified in this resource 
to an icon list resource that is assigned the same local ID in the bundle resource. The 
icon list resource is described on page 7-57; the bundle resource is described in the 
next section. 


a Empty string. This element should always contain an empty Pascal string. 





Figure 7-24 Structure of a compiled file reference ('FREF'') resource 





Resource 


To group together your application’s signature, icon list resource, and file reference 
resources, create a bundle resource. A bundle resource is a resource with the resource 
type 'BNDL'. All bundle resources must have resource ID numbers greater than 128, 
and all must be made purgeable. 





This section describes the structure of the bundle resource after it is compiled by the Rez 
resource compiler. The format of a Rez input file for a bundle resource differs from its 
compiled output form. If you are concerned only with creating a bundle resource, see 
“Creating a Bundle Resource” beginning on page 7-20. 


Finder Interface Reference 7-65 


7-66 


CHAPTER 7 


Finder Interface 





Figure 7-25 Structure of a compiled bundle ('BNDL"') resource 
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If you examine a compiled version of a file reference resource, as illustrated in 
Figure 7-25, you find that it contains the following elements: 


Application signature. This is the unique four-character code that identifies the 
application to the Finder. (Application signatures are described in “Giving a Signature 
to Your Application and a Creator and a File Type to Your Documents” beginning on 
page 7-8.) 


m Resource ID of the signature resource. By convention, this should always be 0. 


m Array count. This element should always contain the value 2. 


= Mapping of local IDs to icon list resource IDs for all icons supplied by the application. 


This is illustrated in Figure 7-26. 


Superfluous local ID mapping for file reference resources. This is illustrated in 
Figure 7-27. 


If you examine the compiled portion of a bundle resource that maps local IDs to icon list 
resource IDs, you find that it contains the following elements: 


Resource type. This element should always specify the resource type 'ICN#' (that is, 
an icon list resource). 


Count of all the icon families supplied by the application. This is the number of local 
ID-to-icon list resource ID mapping pairs in the rest of this resource. 


Local ID for an icon list resource. This local ID must match the local ID assigned to the 
icon list resource within a file reference resource. 


Resource ID for the icon list resource assigned a local ID in the preceding element. To 
visually represent files of the type described in the file reference resource that contains 
the local ID in the preceding element, the Finder uses the black-and-white icon and 
mask described in this icon list resource. The Finder also uses the icons defined in the 
following resources with this same resource ID: small icon list resource, small 4-bit 
color icon resource, small 8-bit color icon resource, large 4-bit color icon resource, and 
large 8-bit color icon resource. 
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Figure 7-26 Mapping local IDs to icon list resource IDs in a bundle resource 
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= Local ID-to-icon list resource ID mapping pairs for the rest of the icons representing 
file types for an application. 


Figure 7-27 illustrates the remainder of a bundle resource, which assigns local IDs to 
file reference resource IDs. This assignment is superfluous because the Finder doesn’t 
map these local IDs to any other resources. This ID assignment was implemented for 
the earliest versions of Macintosh system software, and it remains this way today to 
maintain backward compatibility. 


Figure 7-27 Structure of superfluous local ID mapping for file reference resources in a 
bundle resource 
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If you examine the compiled portion of the remainder of a bundle resource, you find that 
it contains the following elements: 


m Resource type. This element should always specify the resource type 'FREF' (that is, 
a file reference resource). 


m= Count of all the file reference resources representing file types for an application. 
This is the number of local ID-to-file reference resource mapping pairs in the rest of 
this resource. 


m Local ID fora file reference resource. The local ID can be any integer so long as no 
other file reference resource is given that same local ID within this resource. 


m Resource ID for the file reference resource assigned a local ID in the preceding field. 


= Local ID-to-file reference resource ID mapping pairs for the rest of the file reference 
resources that represent file types with application-supplied icons. 


The Missing-Application Name String 


When your application creates a document that the user can open, your application 
should include a missing-application name string in the resource file of the document. 
The missing-application name string is a resource with the resource type 'STR ', it 
must have a resource ID number of —-16396, and it must be made purgeable. The string 
resource should contain your application’s name only. See “Displaying Messages When 
the Finder Can’t Find Your Application” beginning on page 7-27 for additional 
information about copying this resource into the resource fork of your documents. 


If you examine a compiled missing-application name string, as illustrated in Figure 7-28, 
you find that it consists entirely of a Pascal string that names the application that created 
the document. The Finder displays this string in an alert box if the user tries to open or 
print a document created by the application whenever the application is missing. 


Figure 7-28 Structure of a compiled missing-application name string resource 
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The Application-Missing Message String 


When your application creates a document that your application uses but that the user 
cannot open (such as a preferences file), your application should set the creator of the 
document to a registered signature that is not the same as your or anyone else’s 
application, and include an application-missing message string in the resource file of the 
document. The application-missing name string is a resource with the resource type 
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"STR ',it must havea resource ID number of -16397, and it must be made purgeable. 
The string resource should contain a message that explains why the user cannot open or 
print the document, as explained in “Displaying Messages When the Finder Can’t Find 
Your Application” beginning on page 7-27. 

If you examine a compiled application-missing message string, as illustrated in 

Figure 7-29, you find that it consists entirely of a Pascal string that explains why the 
user cannot open the document. The Finder displays this string in an alert box if the user 
tries to open or print a document that is given a special creator that is not used as a 
signature by any application file. (File creators and application signatures are explained 
in “Giving a Signature to Your Application and a Creator and a File Type to Your 
Documents” beginning on page 7-8.) 


Figure 7-29 Structure of a compiled application-missing message string resource 
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The Version Resource 


You can use a version resource in any file so that users can easily find out the version of 
the file and, if it is a part of a larger collection of files, of the entire superset of files. A 
version resource is a resource with the resource type 'vers'. The version resource 
with a resource ID number of 1 specifies the version of an individual file; the version 
resource with a resource ID number of 2 specifies the superset of files to which the 
individual file belongs. 


If your application does not contain a version resource with a resource ID number of 1, 
the Finder displays the string from your application’s signature resource (described 

in “Giving a Signature to Your Application and a Creator and a File Type to Your 
Documents” beginning on page 7-8) in the information window when the user chooses 
the Get Info command from the File menu. 


This section describes the structure of this resource after it is compiled by the Rez 
resource compiler. The format of a Rez input file for a version resource differs from its 
compiled output form. If you are concerned only with creating version resources, see 
“Providing Version Resources” beginning on page 7-31. 


If you examine a compiled version of version resource, as illustrated in Figure 7-30 on 
page 7-70, you find that it contains the following elements: 


m Major revision level in binary-coded decimal format. 


m Minor revision level in binary-coded decimal format. 
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Figure 7-30 Format of a compiled version ('vers') resource 


Development stage. The values that can appear in this field, as well as the constants 
that can be used to specify them in a Rez input file, are the following: 


Value Constant Description 
0x20 development Prealpha file 
0x40 alpha Alpha file 
0x60 beta Beta file 
0x80 release Released file 


Prerelease revision level. This number specifies the version if the software is 
still prerelease. 


Region code. This identifies the script system for which this version of the software is 
intended. See the chapter “Script Manager” in Inside Macintosh: Text for information 
about the values represented by the various region codes that can be specified here. 


Version number. This Pascal string identifies the version number of the software. 
When the user opens the Views control panel, clicks the Show version box, and then 
chooses any command from the View menu other than by Icon or by Small Icon, the 
Finder window containing this application displays this string. 


Version message. This Pascal string identifies the version number and either a 
company copyright for a file or a product name for a superset of files. When the 
user selects this file and chooses the Get Info command, the Finder displays this 
string in the information window as follows: 


For a version resource with a resource ID number of 1, this string is displayed in 
the version field of the information window. 

For a version resource with a resource ID number of 2, this string is displayed 
beneath the file’s name next to the file’s icon at the top of the information window. 
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Summary of the Finder Interface 


Pascal Summary 


Constants 


CONST {Gestalt selectors} 
gestaltFindFolderAttr =! 


{interpreting Gestalt selector responses} 
gestaltFindFolderPresent = 0; 


{for custom icons} 


kCustomIconResource = -—16455; 


{for Finder flags} 

fHasBundle = 8 
fInvisible = 1 
kIsOnDesk = $ 





kColor = 


kIsShared = 


kHasBeenInited = 


kHasCustomIcon = 


kIsStationery = 


kNameLocked = 


kHasBundle = 
kIsInvisible = 





kIsAlias = 
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Foda.; 


, 





$8000; 


{selector for FindFolder} 


{if this bit is set, } 
{ FindFolder is present} 


{resource ID for } 


{ custom icon} 


{set if file has 'BNDL"} 
{set if icon is invisible} 
{unused and reserved in } 

{ System 7} 

{three bits of color coding} 
{file can be executed by } 

{ multiple users } 

{ simultaneously} 

{file info is in desktop } 

{ database} 

{file or directory has a } 

{ customized icon} 

{file is a stationery pad} 
{file or directory can't } 

{ be renamed from Finder, } 
{ and icon can't be changed} 
{file has a bundle resource} 
{file or directory is } 

{ invisible from Finder & } 
{ from Standard File } 

{ Package dialog boxes} 
{file is an alias file} 
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{for FindFolder} 


kOnSystemDisk = $8000; {use vRefNum for the } 
{ boot disk} 

kCreateFolder = TRUE; {create folder if it } 
{ doesn't exist} 

kDontCreateFolder = FALSE; {don't create folder} 


{for special folder types} 


kSystemFolderType = 'macs'; {System Folder} 
kDesktopFolderType = 'desk'; {Desktop Folder} 
kTrashFolderType = 'trsh'; {single-user Trash} 
kWhereToEmptyTrashFolderType = '‘empt'; {shared Trash on network} 
kPrintMonitorDocsFolderType = 'prnt'; {PrintMonitor Documents} 
kStartupFolderType = 'strt'; {Startup Items} 
kFontsFolderType = 'font'; {Fonts} 
kAppleMenuFolderType = ‘amnu'; {Apple Menu Items} 
kControlPanelFolderType = 'ctrl'; {Control Panels} 
kExtensionFolderType = 'extn'; {Extensions} 
kPreferencesFolderType = 'pref'; {Preferences } 
kTemporaryFolderType = 'temp'; {Temporary Items} 
{alias types} 
kContainerFolderAliasType = 'fdrp'; {folder alias} 
kContainerTrashAliasType = 'trsh'; {Trash alias} 
kContainerHardDiskAliasType = 'hdsk'; {hard disk alias} 
kContainerFloppyAliasType = 'flpy'; {floppy disk alias} 
kContainerServerAliasType = 'srvr'; {server alias} 
kApplicationAliasType = 'adrp'; {application alias} 
kContainerAliasType = 'drop'; {all other containers} 
kSystemFolderAliasType = 'fasy'; {System Folder alias} 
kAppleMenuFolderAliasType = 'faam'; {Apple Menu Items folder } 
{ alias} 

kStartupFolderAliasType = 'fast'; {Startup Items folder alias} 
kPrintMonitorDocsFolderAliasType 

= 'fapn'; {PrintMonitor Documents } 


{ folder alias} 


kPreferencesFolderAliasType = 'fapf'; {Preferences folder alias} 
kControlPanelFolderAliasType = 'fact'; {Control Panels folder alias} 
kExtensionFolderAliasType = 'faex'; {Extensions folder alias} 
kExportedFolderAliasType = 'faet'; {export folder alias} 
kDropFolderAliasType = 'fadr'; {drop folder alias} 
kSharedFolderAliasType = 'fash'; {shared folder alias} 
kMountedFolderAliasType = 'famn'; {mounted folder alias} 
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Data Types 


TYPE 


{Finder information records in the volume catalog file} 


FInfo = 
RECORD 
fdType: 
fdCreator: 
fdFlags: 
fdLocation: 
fdFldr: 
END; 


FXInfo = 

RECORD 
fdiIconID: 
fdUnused: 


fdScript: 

fdxFlags: 

fdComment : 

fdPutAway: 
END; 


Dinfo = 

RECORD 
frRect: 
frFlags: 





frLocation: 
frView: 
END; 


DXInfo = 

RECORD 
frScroll: 
frOpenChain: 
frScript: 
frxXFlags: 
frComment: 
frPutAway: 

END; 


OSType; 
OSType; 
Integer; 
Point; 
Integer; 


Integer; 
ARRAY[1..3] OF 


SignedByte; 
SignedByte; 
Integer; 
LongInt; 


Rect; 
Integer; 
Point; 
Integer; 


Point; 
LongInt; 
SignedByte; 
SignedByte; 
Integer; 
LongInt; 
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{file type} 

{file creator} 

{Finder flags} 

{file's location in window} 


{directory that contains file} 


{icon ID} 

Integer; 

{unused but reserved 6 bytes} 
{script flag and code} 
{reserved} 

{comment ID} 

{home directory ID} 


{folder's window rectangle} 
{flags} 

{folder's location in window} 
{folder's view} 


{scroll position} 

{dir ID chain of open folders} 
{script flag and code} 
{reserved} 

{comment ID} 

{directory ID} 


7-73 


CHAPTER 7 


Finder Interface 


Routines 


Resolving Alias Files 


FUNCTION ResolveAliasFile (VAR theSpec: FSSpec; 
resolveAliasChains: Boolean; 
VAR targetIsFolder: Boolean; 
VAR wasAliased: Boolean): OSErr; 


Finding Directories 


FUNCTION FindFolder (vRefNum: Integer; folderType: OSType; 
createFolder: Boolean; 
VAR foundVRefNum: Integer; 
VAR foundDirID: LongInt): OSErr; 





C Summary 


Constants 


enum { 
/*Gestalt selectors*/ 
#define gestaltFindFolderAttr 'fold' /*selector for FindFolder*/ 


/*interpreting Gestalt selector responses*/ 
gestaltFindFolderPresent = 0 /*if this bit is set, */ 
/* FindFolder is present*/ 
}; 
/*for custom icons*/ 
#define kCustomIconResource -16455 /*resource ID for */ 


/* custom icon*/ 


/*Finder flags*/ 


#define kIsOnDesk Ox /*unused and reserved in */ 
/* System 7*/ 

#define kColor OxE /*3 bits of color coding*/ 

#define kiIsShared 0x40 /*file can be executed by */ 


/* multiple users */ 
/* simultaneously*/ 





#define kHasBeenInited 0x100 /*file info is in desktop */ 
/* database*/ 
#define kHasCustomIcon 0x400 /*file or directory has a */ 


/* customized icon*/ 


7-74 Summary of the Finder Interface 


CHAPTER 7 


Finder Interface 


#define kIsStationary 
#define kNameLocked 
#define kHasBundle 
#define kIsInvisible 
#define kIsAlias 

enum { 


hi 


enum { 


/*for Finder flags*/ 
fHasBundle 
fInvisible 


/*for FindFolder*/ 
kOnSystemDisk 


#define kCreateFolder 


#define kDontCreateFolder 


/*for special folder types*/ 
#define kSystemFolderType 
#define kDesktopFolderType 


#define kTrashFolderType 





0x800 
0x1000 


0x2000 


0x4000 


0x8000 


= 8192, 
= 16384 


0x8000 


true 


false 


"macs' 


"desk' 
‘trsh' 


#define kWhereToEmptyTrashFolderType 
"empt' 
#define kPrintMonitorDocsFolderType 
"prnt' 
#define kStartupFolderType "strt' 
#define kFontsFolderType Vtont:' 
#define kAppleMenuFolderType "amnu' 
#define kControlPanelFolderType 'ctrl' 
#define kExtensionFolderType ‘extn! 
#define kPreferencesFolderType 'pref' 
#define kTemporaryFolderType "temp' 
}; 
/*for alias types*/ 
#define kContainerFolderAliasType "fdrp' 
#define kContainerTrashAliasType "trsh' 
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/*file is a stationery pad*/ 
/*file or directory can't */ 
/* be renamed from the */ 

/* Finder, 
/* be changed*/ 

/*file has a bundle */ 
/* resource*/ 


and icon can't */ 


/*file or directory is */ 
/* invisible from Finder */ 
/* & from Standard File */ 
/* Package dialog boxes*/ 
/*file is an alias file*/ 


/*set if file has 'BNDL'*/ 
/*set if icon is invisible*/ 


/*use vRefNum for the */ 
/* boot disk*/ 

/*create folder if it */ 
/* doesn't exist*/ 
/*don't create folder*/ 


/*System Folder*/ 
/*Desktop Folder*/ 
/*single-user Trash*/ 


/*shared Trash*/ 


/*PrintMonitor Documents*/ 
/*Startup Items*/ 
/*Fonts*/ 

/*Apple Menu Items*/ 
/*Control Panels*/ 
/*Extensions*/ 
/*Preferences*/ 
/*Temporary Items*/ 


/*folder alias*/ 
/*Trash alias*/ 
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#define 
#define 
#define 
#define 
#define 
#define 
#define 


#define 


#define 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
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kContainerHardDiskAliasType 
kContainerFloppyAliasType 
kContainerServerAliasType 
kApplicationAliasType 
kContainerAliasType 
kSystemFolderAliasType 
kAppleMenuFolderAliasType 


kStartupFolderAliasType 


"hdsk' /*hard disk alias*/ 

'flpy' /*floppy disk alias*/ 

'srvr' /*server alias*/ 

"adrp' /*application alias*/ 

"drop' /*all other containers*/ 

"fasy' /*System Folder alias*/ 

'faam' /*Apple Menu Items folder */ 
/* alias*/ 

‘fast! /*Startup Items folder */ 


/* alias*/ 


kPrintMonitorDocsFolderAliasType 


kPreferencesFolderAliasType 
kControlPanelFolderAliasType 
kExtensionFolderAliasType 
ExportedFolderAliasType 
DropFolderAliasType 
SharedFolderAliasType 





k 
k 
k 
k 


MountedFolderAliasType 


Data Types 


struct FInfo { 


OSType fdType; 
OSType fdCreator; 
unsigned short fdFlags; 
Point fdLocation; 
short fdFldr; 


}; 


struct FXInfo { 


short fdiIconID; 
short fdUnused[3]; 
char fdScript; 
char fdxFlags; 
short fdComment; 
long fdPutAway; 


he 
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'fapn' /*PrintMonitor Documents */ 
/* folder alias*/ 

'fapf' /*Preferences folder alias*/ 

"fact! /*Control Panels fldr alias*/ 

"faex' /*Extensions folder alias*/ 

'faet' /*export folder alias*/ 

'fadr' /*drop folder alias*/ 

'fash' /*shared folder alias*/ 

'famn' /*mounted folder alias*/ 


/*Finder information records in the catalog file*/ 


/*file type*/ 

/*file creator*/ 

/*Finder flags*/ 

/*file's location in window*/ 


/*directory that contains file*/ 


/*icon ID*/ 

/*unused but reserved 6 bytes*/ 
/*script flag and code*/ 
/*reserved*/ 

/*comment ID*/ 


/*home directory ID*/ 
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struct DInfo { 


}; 


Rect 
unsigned short 
Point 
short 


struct DXInfo { 


hi 


Point 
long 
char 
char 
short 
long 


Routines 


Resolving Alias Files 





pascal OSErr ResolveA 


Finding Directories 


pascal OSErr FindFold 





7 


frRect; /*folder's window rectangle*/ 
frFlags; /*flags*/ 
frLocation; /*folder's location in window*/ 
frView; /*folder's view*/ 
frScroll; /*scroll position*/ 
frOpenChain; /*directory ID chain of open folders*/ 
frScript; /*script flag and code*/ 


frxFlags; 


frComment; 


/*reserved*/ 
/*comment ID*/ 


frPutAway; /*directory ID*/ 


liasFile 





(FSSpec *theSpec, Boolean resolveAliasChains, 


Boolean *targetIsFolder, Boolean *wasAliased) ; 


er (short vRefNum, OSType folderType, 





Boolean createFolder, short *foundVRefNum, 


long *foundDirID); 


Assembly-Language Summary 


Data Structures 


FInfo Data Structure 


10 
14 


fdType 
fdCreator 
fdFlags 
fdLocation 
fdFldr 


long 
long 
word 
long 
word 


file type 

file creator 

Finder flags 

file’s location in window 
directory that contains file 
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FXInfo Data Structure 


0 fdIconID word 
2 fdUnused 6 bytes 
8 fdScript 1 byte 
9 fdXFlags 1 byte 
10 fdComment word 
12 fdPutAway long 


DInfo Data Structure 





icon ID 

reserved 

script flag and code 
reserved 

comment ID 

home directory ID 


folder’s window rectangle 
flags 

folder’s location in window 
folder’s view 


scroll position 

directory ID chain of open folders 
script flag and code 

reserved 

comment ID 

directory ID 


Volume not found 
For FindFolder: Type not found in '£1d#"' resource, or disk doesn’t have 


System Folder support or System Folder in volume header, or disk does not 
have desktop database support for Desktop Folder—in all cases, folder not 


For ResolveAliasFile: Target not found, but volume and parent 
directory found and theSpec parameter contains a valid file system 
specification record 


0 frRect 8 bytes 
8 frFlags word 
10 frLocation long 
14 frview word 
DXInfo Data Structure 
0 frScroll long 
4 frOpenChain long 
8 frScript 1 byte 
9 frXFlags 1 byte 
10 frComment word 
12 frPutAway long 
Result Codes 
noErr 0 No error 
nsvErr -35 
fnfErr 43 
found 
dupFNErr 48 
dirNFErr -120 





File found instead of folder 
Parent directory not found 
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Glossary 


action procedure A procedure that performs an 
action in response to the user holding the mouse 
button down while the cursor is in a control. 


activate event A type of event that indicates 
that a window is becoming active or inactive. 
Each activate event specifies the window 

to be changed and the direction of the change 
(that is, whether it’s becoming active or 
becoming inactive). 


active control A control in which the Control 
Manager responds to a user’s mouse actions by 
providing visual feedback. 


active window The frontmost window on the 
desktop, the one in which the user is currently 
working. The active window is designated by 
racing stripes in the title bar, active controls, and 
highlighted selections. 


A5 world An area of memory in an applica- 
tion’s partition that contains the QuickDraw 
gloabl variables, the application global variables, 
the application parameters, and the jump table— 
all of which are accessed through the A5 register. 


alert An alert sound, an alert box, or both. 
Alerts warn the user of an unusual or a 
potentially undesirable situation occurring 
within an application. See also alert box and 
alert sound. 


alert box A window that an application 
displays on the screen to warn the user or to 
report an error to the user. An alert box typically 
consists of text describing the situation and 
buttons that require the user to acknowledge or 
rectify the problem. An alert box may or may not 
be accompanied by an alert sound. See also 
caution alert, note alert, and stop alert. 


alert color table resource A resource (of type 
‘actb') that lets an application display an alert 
box using colors other than the system’s default 
window colors. 


alert resource A resource (of type 'ALRT"') that 
specifies alert sounds, a display rectangle, and an 
item list for an alert box. 


alertsound An audible signal from the 
Macintosh speaker that warns the user of an 
unusual or a potentially undesirable situation 
occurring within an application. An alert sound 
may or may not be accompanied by an alert box. 


alias An object that represents another file, 
directory, or volume. 


alias file A file that contains a record that 
points to another file, directory, or volume. An 
alias file is displayed by the Finder as an alias. 


alias record A data structure created by the 
Alias Manager to identify a file, directory, 
or volume. 


alias target The file, directory, or volume 
described by the alias record. 


Apple event A high-level event whose 
structure and interpretation are determined by 
the Apple Event Interprocess Messaging Protocol. 


Apple Menu Items folder A directory located 
in the System Folder for storing desk accessories, 
applications, folders, and aliases that the 

user wants to display in and access from the 
Apple menu. 


application heap An area of memory in 

the application heap zone in which memory is 
dynamically allocated and released on demand. 
The heap contains the application’s 'CODE' 
segment 1, data structures, resource map, and 
other code segments as needed. 





application partition A partition of memory 
reserved for use by an application. The applica- 
tion partition consists of free space, the 
application heap, the application’s stack, and 
the application’s A5 world. 
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auto-key event An event indicating that a 
key is still down after a certain amount of time 
has elapsed. 


auxiliary window record A data structure that 

the Window Manager uses to tie together a list of 
windows and their corresponding window color 

information tables. 


background process A process that isn’t 
currently interacting with the user. Compare 
foreground process. 


bundle bit A flag ina file’s Finder information 
record that informs the Finder that a bundle 
('BNDL") resource exists for the file. A file’s 
Finder information record is stored in a volume’s 
catalog file. The Finder uses the information 

in the bundle resource to associate icons with 
the file. 


button A control that appears on the screen as a 
rounded rectangle with a title centered inside. 
When the user clicks a button, the application 
performs the action described by the button’s 
title. Button actions are usually performed 
instantaneously. Examples include completing 
operations defined by a dialog box and 
acknowledging an error message in an alert box. 


catalog file A special file, located on a volume, 
that contains information about the hierarchical 
organization of files and folders on that volume. 


caution alert An alert box that warns the user 
of an operation that may have undesirable results 
if it’s allowed to continue. A caution alert gives 
the user the choice of continuing the action (by 
clicking the OK button) or stopping the action 
(by clicking the Cancel button). A caution alert is 
identified by an icon bearing an exclamation 
point in the upper-left corner of the alert box. See 
also note alert and stop alert. 


character code A value that represents a 
particular character. The character code that is 
generated depends on the virtual key code and 
the state of the modifier keys. In the Roman 
script system, character codes are specified in 
the extended version of ASCII (the American 
Standard Code for Information Interchange). 


checkbox A control that appears onscreen as a 
small square with an accompanying title. A 
checkbox displays one of two settings: on 
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(indicated by an X inside the box) or off. When 
the user clicks a checkbox, the application 
reverses its setting. See also radio button. 


close box The small white box on the left side 
of the title bar of an active window. Clicking it 
closes the window. 


close region The area occupied by a window’s 
close box. See also close box. 


Command-key equivalent Refers specifically 
to a keyboard equivalent that the user invokes by 
holding down the Command key and pressing 
another key (other than a modifier key) at the 
same time. 


content region The part of a window in which 
the contents of a document, the size box, and 
the window controls (including the scroll bars) 
are displayed. 


context The information about a process 
maintained by the Process Manager. This 
information includes the current state of the 
process, the address and size of its partition, its 
type, its creator, a copy of its low-memory global 
variables, information about its 'SIZE' resource, 
and a process serial number. 





control An onscreen object that the user can 
manipulate with the mouse. By manipulating a 
control, the user can take an immediate action or 
change a setting to modify a future action. 


control color table In an item color table 
resource, a specification for the colors used to 
draw the various parts of a control. 


control definition function A function that 
defines the appearance and behavior of a control. 
A control definition function, for example, draws 
the control. See also standard control definition 
functions. 


control definition ID A number passed to 
control-creation routines to indicate the type of 
control. It consists of the control definition 
function’s resource ID and a variation code. 


control list A series of entries pointing to the 
descriptions of the controls associated with 
the window. 


GLOSSARY 


Control Manager A collection of routines that 
applications use to create and manipulate 
controls, especially those in windows. 


Control Panels folder A directory located in 
the System Folder for storing control panels, 
which allow users to modify the work 
environment of their Macintosh computer. 


control record A data structure of type 
ControlRecord, which the Control Manager 
uses to store all the information it needs for its 
operations on a control. 


current menu list A data structure that contains 
handles to the menu records of all menus in the 
current menu bar and the menu records of any 
submenus or pop-up menus that an application 
inserts into the list. 


current process The process that is currently 
executing and whose A5 world is valid; this 
process can be in the background or the 
foreground. 


cursor Any 256-bit image, defined by a 
16-by-16 bit square. The mouse driver displays 
the current cursor and maps the movement 

of the mouse to relative locations on the screen 
as the user moves the mouse. 


custom alert box An alert box whose upper-left 
corner contains blank space or displays an icon 
other than those used by caution alerts, stop 
alerts, or note alerts. 


customized icon An icon created by the user or 
by an application and stored with a resource ID 
of —16455 in the resource fork of a file. A file with 
a customized icon has the hasCustomIcon bit 
set in its Finder flags field. 


data fork The part of a file that contains data 
accessed using the File Manager. The data 
usually corresponds to data entered by the user; 
the application creating a file can store and 
interpret the data in the data fork in whatever 
manner is appropriate. 


default button In an alert box or a dialog box, 
the button whose action is invoked when the 
user presses the Return key or the Enter key. The 
Dialog Manager automatically draws a bold 
outline around the default button in alert boxes; 
applications should draw a bold outline around 


the default button in dialog boxes. The default 
button should invoke the preferred action, which, 
whenever possible, should be a “safe” action— 
that is, one that doesn’t cause loss of data. 


desktop The working environment displayed 
on the Macintosh computer: the gray background 
area on the screen. 


desktop database A Finder-maintained 
database of icons, file types, applications, version 
data, and comments for all volumes over 2 MB. 
Compare Desktop file. 


Desktop file A resource file in which the Finder 
stores icons, file types, applications, version data, 
and comments for all volumes less than 2 MB. 
Compare desktop database. 


Desktop Folder A directory, located at the root 
level of each volume, used by the Finder for 
storing information about the icons that appear 
on the desktop area of the screen. The Desktop 
Folder is invisible to the user. What the user sees 
onscreen is the union of the contents of Desktop 
Folders for all mounted volumes. 


dial A control, similar to a scroll bar, that 
graphically represents the ranges of values that 
a user can set or that simply displays the value, 
magnitude, or position of something, typically in 
some pseudo-analog form. 


dialog box A window that an application 
displays on the screen to solicit information 
from the user before the application carries 

out the user’s command. See also modal dialog 
box, modeless dialog box, and movable modal 
dialog box. 


dialog color table resource A resource (of type 
‘dctb') that lets an application display a dialog 
box using colors other than the system’s default 
window colors. 


Dialog Manager A collection of routines that 
applications use to implement alerts and dialog 
boxes. 


dialog record A data structure of type 
DialogRecord that the Dialog Manager 
uses to create dialog boxes and alerts. 


dialog resource A resource (of type 'DLOG') 
that specifies the window type, display rectangle, 
and item list for a dialog box. 
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disabled item In an alert box or a dialog box, 
an item for which the Dialog Manager does 

not report user events. An example of a disabled 
item is static text, which typically does not 
respond to clicks. 


disk-inserted event An event indicating that a 
disk has been inserted into a disk drive. 


display rectangle A rectangle that defines the 
size and location of an item in an alert box or a 
dialog box. The display rectangle is specified in 
an item list and uses coordinates local to the alert 
box or dialog box. 


divider A gray line used in menus to separate 
groups of menu items. 


document window A window in which the 
user enters text, draws graphics, or otherwise 
enters or manipulates data. 


dragregion The area occupied by a window’s 
title bar, except for the close box and zoom box. 
The user can move a window on the desktop by 
dragging the drag region. 


edition The data written to an edition container 
by a publisher. A publisher writes data to an 
edition whenever a user saves a document that 
contains a publisher, and subscribers in other 
documents may read the data from the edition 
whenever it is updated. 


enabled item In an alert box or a dialog box, 
an item for which the Dialog Manager reports 
user events. For example, the Dialog Manager 
reports clicks in an enabled OK button. 


event The means by which the Event Manager 
communicates information about user actions, 
changes in the processing status of the 
application, and other occurrences that require a 
response from the application. 


event filter function An application-defined 
routine that supplements the Dialog Manager’s 
ability to handle events—for example, an event 
filter function can test for disk-inserted events 
and can allow background applications to receive 
update events. 


Event Manager The collection of routines that 
an application can use to receive information 
about actions performed by the user, to receive 
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notice of changes in the processing status of 
the application, and to communicate with 
other applications. 


event mask An integer with one bit position for 
each event type. You specify an event mask as a 
parameter to Event Manager routines to specify 
the event types you want your application to 
receive, thereby disabling (or “masking out”) the 
events you are not interested in receiving. 


event record A data structure of type 
EventRecord that your application uses when 
retrieving information about an event. The Event 
Manager returns, in an event record, information 
about what type of event occurred (a mouse click 
or keypress, for example) and additional informa- 
tion associated with the event. 





Extensions folder A directory located in the 
System Folder for storing system extension files 
such as printer and network drivers and files of 
types 'INIT', 'scri',and 'appe'. 


file A named, ordered sequence of bytes stored 
on a Macintosh volume, divided into a data fork 
and a resource fork. 


Finder An application that works with the 
system software to keep track of files and 
manage the user’s desktop display. 


Fonts folder A directory located in the System 
Folder for storing fonts. 


foreground process The process currently 
interacting with the user; it appears to the user as 
the active application. The foreground process 
displays its menu bar, and its windows are in 
front of the windows of other applications. 
Compare background process. 


frame The part of a window drawn 
automatically by the Window Manager, namely, 
the title bar, including the close box and zoom 
box, and the window’s outline. 


global coordinate system The coordinate 
system that represents all potential QuickDraw 
drawing space. The origin of the global 
coordinate system—that is, the point (0,0)— 

is at the upper-left corner of the main screen. 
Compare local coordinate system. 


GLOSSARY 


graphics port A complete, individual drawing 
environment with an independent coordinate 
system. Each window is drawn ina graphics port. 


gray area The area within a scroll bar, excluding 
the scroll arrows and the scroll box. When the 
user clicks the gray area of a scroll bar, the 
application moves the displayed area of the 
document by an entire window less one line (or 
column, row, or character). 


gray region A region that represents all 
available desktop area—that is, a collection 
of rounded-corner rectangles representing 
the display areas of all monitors available to 
a computer. 


grow image An outline of a window’s new 
frame, drawn on the screen while the user is 
resizing the window with the size box. 


help balloon A rounded-rectangle window that 
contains explanatory information for the user. 
With tips pointing at the objects they annotate, 
help balloons look like bubbles used for dialog in 
comic strips. Help balloons are turned on by the 
user from the Help menu; when Balloon Help 
assistance is on, a help balloon appears whenever 
the user moves the cursor over an area that is 
associated with it. 


hierarchical menu A menu to whicha 
submenu is attached. 


high-level event An event sent from one 
application to another requesting transfer of 
information or performance of some action. 


high-level event queue A separate queue that 
the Event Manager maintains to store high-level 
events transmitted to an application. The Event 
Manager maintains a high-level event queue for 
each open application capable of receiving 
high-level events. 


hot spot A point that the mouse driver uses to 
align the cursor with the mouse location. 


icon An image that represents an object, a 
concept, or a message. 


icon family The set of icons that represent an 
object—such as an application or a document— 
displayed by the Finder. An entire icon family 
consists of large (32-by-32 pixel) and small 


(16-by-16 pixel) icons, each with a mask, and 
each available in three different versions of color: 
black and white, 4 bits of color data per pixel, 
and 8 bits of color data per pixel. 


inactive control A control that has no meaning 
or effect in the current context—for example, the 
scroll bars in an empty window. The Control 
Manager dims inactive controls or otherwise 
visually indicates their inactive state. 


inactive window A window in which the user 
is not working. 


indicator A moving part ina dial or slider 
control. A user moves an indicator to set a value, 
and an application moves it to indicate the 
current setting of the control. In a scroll bar, the 
scroll box is the indicator. 


item color table resource A resource (of type 
"ictb') that an application can use to display 
an alert box or a dialog box with items using a 
typeface, font style, font size, or colors other 
than the system’s default font and colors. (For 
an application to use a nonstandard typeface, 
font style, or font size, the user must have a 
color monitor.) 


item list A resource (of type 'DITL") that 
specifies the items—such as buttons and static 
text—to display in an alert box or a dialog box. 


item number An integer that identifies an item 
in either a menu or a dialog box. Menu items 

are assigned item numbers starting with 1 for 
the first menu item in the menu, 2 for the second 
menu item in the menu, and so on, up to the 
number of the last menu item in the menu. 
Dialog items are assigned numbers that 
correspond to the item’s position in its item list. 
For example, the first item listed in a dialog item 
list is item number 1. 


keyboard equivalent A keyboard combination 
of one or more modifier keys and another key 
that invokes a corresponding menu command 
when pressed by the user. 


key-down event An event indicating that the 
user pressed a key on the keyboard. 


key-up event Anevent indicating that the user 
released a key on the keyboard. 
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local coordinate system The coordinate system 
defined by the port rectangle of a graphics port. 
When the Window Manager creates a window, it 
places the origin of the local coordinate system at 
the upper-left corner of the window’s port 
rectangle. Compare global coordinate system. 


location name _ An identifier for the network 
location of the computer on which a PPC port 
resides. A location name consists of an object 
string, a type string, and a zone. 


low-level event The type of event returned by 
the Event Manager to report very low level 
hardware and software occurrences. Low-level 
events report actions by the user, changes in 
windows on the screen, and that the Event 
Manager has no other events to report. Compare 
high-level event, operating-system event. 


major switch A change of the foreground 
process. The Process Manager switches the 
context of the foreground process with the 
context of a background process (including the 
A5 worlds and low-memory global variables) 
and brings the background process to the front, 
sending the previous foreground process to the 
background. See also context. 


menu A user interface element you can use in 
your application to allow the user to view or 
choose an item from a list of choices and 
commands that your application provides. 

See also hierarchical menu, pop-up menu, 
pull-down menu, and submenu. 


menu bar A white rectangle that is tall enough 
to display menu titles in the height of the system 
font and system font size, and with a black lower 
border that is one pixel tall. The menu bar 
extends across the top of the startup screen and 
contains the title of each available pull-down 
menu. 


menu bar definition function A function that 
draws the menu bar and performs most of the 
drawing activities related to the display of menus 
when the user moves the cursor between menus. 
This function, in conjunction with the menu 
definition procedure, defines the general 
appearance and behavior of menus. 
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menu barentry A menu color entry record that 
contains 0 in both the mct ID andmct Item 
fields. A menu bar entry defines the color for an 
application’s menu bar and defines default colors 
for its menu titles, menu items, and background 
color of menus. 


menu barresource A resource (of type 
"MBAR ') that specifies the order and resource ID 
of each menu in a menu bar. 





menu color entry record A data structure of 
type MCEntry that defines the colors for an 
application’s menu bar, menus, or menu items. 
The first two fields of a menu color entry record, 
mct ID andmct Item, define whether the entry 
is amenu bar entry, a menu title entry, or a menu 
item entry. 





menu color information table An array of 
menu color entry records, maintained by the 
Menu Manager, that define the standard color 
for the menu bar, titles of menus, text and 
characteristics of menu items, and background 
color of a displayed menu. If you do not add 

any entries to this table, the Menu Manager 
draws your menus using the default colors, black 
on white. 


menu color information table resource A 
resource (of type 'mctb') that specifies the 
colors for an application’s menu bar, menus, 
and menu items. 


menu definition procedure A procedure that 
performs all the drawing of menu items within 
a specific menu. This procedure, in conjunction 
with the menu bar definition function, defines 

the general appearance and behavior of menus. 


menuID A number that you assign to a menu 
in your application. Each menu in your applica- 
tion must have a unique menu ID. 


menuitem Ina menu,a rectangle with text and 
other characteristics identifying a command that 
the user can choose. 


menu item entry A menu color entry record 
that contains nonzero values in both the mct ID 
and mct Item fields. A menu item entry defines 
colors for the mark, text, and keyboard 
equivalent of items in a specific menu. It also 
defines the default background color of a menu. 
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menu list A data structure that contains 
handles to the menu records of one or more 
menus (although a menu list can be empty). 
Compare current menu list. 


Menu Manager The collection of routines that 
an application can use to create, display, and 
manage its menus. 


menu record A data structure of type 
MenuInfo that the Menu Manager uses to 
maintain information about a menu. 


menu resource A resource (of type 'MENU') 
that specifies the menu title and the individual 
characteristics of items in a menu. 


menu title entry A menu color entry record 
that contains a nonzero value in the mct ID 
field and contains 0 in the mct Item field. A 
menu title entry defines colors for the title, 
items, and background color of a specific menu. 
It also defines the default menu bar color. 


minimum partition size The actual partition 
size limit below which an application cannot run. 


minor switch A change in the context of a 
process. The Process Manager switches the 
context of a process to give time to a background 
process without bringing the background process 
to the front. 


modal dialog box A dialog box that puts the 
user in the state or “mode” of being able to work 
only inside the dialog box. A modal dialog box 
resembles an alert box. The user cannot move a 
modal dialog box and can dismiss it only by 
clicking its buttons. See also modeless dialog box 
and movable modal dialog box. 


modeless dialog box A dialog box that looks 
like a document window without a size box or 
scroll bars. The user can move a modeless dialog 
box, make it inactive and active again, and close 
it like any document window. See also modal 
dialog box and movable modal dialog box. 


modifier keys The Shift, Option, Command, 
Control, and Caps Lock keys. 


mouse-down event An event indicating that 
the user pressed the mouse button. 


mouse location ‘The location of the cursor at the 
time the event occurred. 


mouse-moved event An event indicating that 
the cursor is outside of a specified region. 


mouse-up event An event indicating that the 
user released the mouse button. 


movable modal dialog box A modal dialog box 
that has a title bar (with no close box) by which 
the user can drag the dialog box. See also dialog 
box, modal dialog box, and modeless dialog box. 


note alert An alert box that informs users of a 
minor mistake that won't have any disastrous 
consequences if left as is. Usually a note alert 
simply offers information, and the user responds 
by clicking the OK button. A note alert is 
identified by an icon bearing a face and a 
cartoonlike dialog balloon in the upper-left 
corner of the alert box. See also caution alert and 
stop alert. 


null event An event indicating that no events 
of the requested types exist in the application’s 
event stream. 


offset point The point in a region whose 
horizontal and vertical offsets from the upper-left 
corner of the region’s enclosing rectangle are the 
same as the offsets of a specified point. The 
DrayGrayRgn function uses an offset point to 
limit the motion of a region and to calculate the 
distance a region has moved. 


operating-system event An event returned by 
the Event Manager to communicate information 
about changes in the operating status of 
applications (suspend and resume events) and to 
report that the user has moved the cursor outside 
of an area specified by the application (mouse- 
moved events). Compare low-level event, 
high-level event. 


Operating System Event Manager The 
collection of low-level routines that manage the 
Operating System event queue. 


Operating System event queue A queue that 
the Operating System Event Manager creates and 
maintains. The Operating System Event Manager 
detects and reports low-level hardware-related 
events such as mouse clicks, keypresses, and disk 
insertions and places these events in the 
Operating System event queue. 
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partcode An integer from 1 through 253 that 
stands for a particular part of a control. The 
FindControl and TrackControl functions 
return a part code to indicate the location of the 
cursor when the user presses the mouse button. 


pop-up menu A menu that appears elsewhere 
than the menu bar. The Control Manager 
provides a control definition function for 
applications to use when implementing pop- 
up menus. 


portname A unique identifier for a particular 
application on a computer, used for the purposes 
of communication between applications. A port 
name consists of a name string, a type string, and 
a script code. 


port rectangle Anentry in the graphics port 
data structure, described in Inside Macintosh: 
Imaging. Ordinarily, the port rectangle represents 
the area of a graphics port available for 
drawing—that is, the content region of a window. 


Preferences folder A directory located in the 
System Folder for holding files that record users’ 
configuration settings for applications on a 
particular Macintosh computer. 


preferred partition size The partition size at 
which an application can run most effectively. 
The Operating System attempts to secure this 
partition size upon launch of the application. 


PrintMonitor Documents folder A directory 
located in the System Folder for storing spooled 
documents waiting to be printed. 


process An open application or, in some cases, 
an open desk accessory. (Only desk accessories 
that are not opened in the context of another 
application are considered processes.) 


process serial number A number assigned by 
the Process Manager to identify a particular 
instance of an application during a single boot 
of the local machine. 


pull-down menu A menu that is identified by a 
menu title (a word or an icon) in the menu bar. 


query document A file of file type 'gery' 
containing commands and data in a format 
appropriate for a database or other data source. 
An application uses high-level Data Access 
Manager routines to open a query document. 
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radio button A control that appears onscreen as 
a small circle. A radio button displays one of two 
settings: on (indicated by a black dot inside the 
circle) or off. A radio button is always a part of a 
group of related radio buttons in which only one 
button can be on at a time. When the user clicks 
an unmarked radio button, the application turns 
that button on and turns the other buttons in its 
group off. 


Rescued Items from volume name folder A 
directory located in the Trash directory and 
created by the Finder at system startup, restart, 
or shutdown only when it finds items in the 
Temporary Items folder, usually after a system 
crash. The Rescued Items from volume name 
folder is named for the volume on which the 
Temporary Items folder exists. When a user 
empties the Trash, all Rescued Items folders 
disappear. 


resource Any data stored according toa 
defined structure in a resource fork of a file; the 
data in a resource is interpreted according to its 
resource type. 


resource fork The part of a file that contains the 
files’ resources. A resource fork consists of a 
resource map and resources. 


resource ID A number that identifies a specific 
resource of a given resource type. 


resource type A sequence of four characters 
that uniquely identifies a specific type of resource. 


resume event An event indicating that an 
application has been switched back into the 
foreground and can resume interacting with 
the user. 


return receipt A high-level event that indicates 
whether the other application accepted the 
high-level event sent to it by your application. 


scroll arrow An arrow at either end of a scroll 
bar. When the user clicks a scroll arrow, the 
application moves a document or list one line 
(or some similar measure) in the direction of the 
arrow. When the user holds the mouse button 
down while the cursor is over a scroll arrow, 
the application moves the document or list 
continuously in the direction of the arrow. 
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scroll bar A control with which the user can 
change the portion of a document displayed 
within a window. A scroll bar is a light gray 
rectangle with scroll arrows at each end. 
Windows can have a horizontal scroll bar, a 
vertical scroll bar, or both. A vertical scroll bar 
lies along the right side of a window. A 
horizontal scroll bar runs along the bottom of 
a window. Inside the scroll bar is a rectangle 
called the scroll box. The rest of the scroll bar 
is called the gray area. The user can move 
through a document by manipulating the parts 
of the scroll bar. 


scroll box A box that slides up and down or 
back and forth across a scroll bar. The position of 
the scroll box in a scroll bar indicates the position 
of the window contents relative to the entire 
document. When the user drags the scroll box, 
the application displays a different portion of 

the document. 


signature A resource whose type is defined by 
a four-character sequence that uniquely identifies 
an application to the Finder. A signature is 
located in an application’s resource fork. 


size box A box in the lower-right corner of 
windows that can be resized. Dragging the size 
box resizes the window. 


size region The area occupied by a window’s 
size box. See also size box. 


sizeresource A resource (of type 'SIZE') that 
specifies the operating characteristics, minimum 
partition size, and preferred partition size of 

an application. 


slider A control, such as a scroll bar, that 
graphically represent the ranges of values that 
a user can set or that simply displays the value, 
magnitude, or position of something, typically 
in some pseudo-analog form. 


standard control definition functions Three 
control definition functions, stored as 'CDEF' 
resources in the System file. The 'CDEF' 
resource with resource ID 0 defines the look and 
behavior of buttons, checkboxes, and radio 
buttons; the 'CDEF' resource with resource ID 1 
defines the look and behavior of scroll bars; and 
the 'CDEF' resource with resource ID 63 defines 
the look and behavior of pop-up menus. 


standard state The size and location that 
an application deems the most convenient for 
a window. 


Startup Items folder A directory located in the 
System Folder for storing applications and desk 
accessories that the user wants started up every 
time the Finder starts up. 


stationery pad A document that a user creates 
to serve as a template for other documents. The 
Finder tags a document as a stationery pad by 
setting the isStationery bit in the Finder 
flags field of the file’s file information record. 
An application that is asked to open a stationery 
pad should copy the template’s contents into a 
new document and open the document in an 
untitled window. 


stop alert An alert box that informs the user of 
a problem or situation so serious that the user’s 
desired action cannot be completed. Stop alerts 
typically have only a single button (OK), because 
all the user can do is acknowledge that the action 
cannot be completed. A stop alert is identified by 
an icon of an upraised hand in the upper-left 
corner of the alert box. See also caution alert and 
note alert. 


structure region The entire screen area 
occupied by a window, including both the 
window frame and the content region. 


submenu A menu that is attached to 
another menu. 


suspend event An event indicating that the 
execution of your application is about to be 
suspended as the result of a major switch. 

The application is suspended at the application’s 
next call to WaitNextEvent orEventAvail. 








system alertsound A sound resource that is 
stored in the System file and played whenever 
system software or an application uses the Sound 
Manager procedure SysBeep. With the Sound 
control panel, the user can select which sound 

to use. 


System file A file, located in the System Folder, 
that contains the basic system software plus some 
system resources, such as sound and keyboard 
resources.The System file behaves like a folder in 
this regard: although it looks like a suitcase icon, 
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double-clicking it opens a window that reveals 
movable resource files (such as sounds, keyboard 
layouts, and script system resource collections) 
stored in the System file. 


System Folder A directory containing the 
software that Macintosh computers use to start 
up. The System Folder includes a set of folders 
for storing related files, such as preferences files 
that an application might need when starting up. 


Temporary Items folder A directory located at 
the root level of a volume for storing temporary 
buffer files created by applications. The 
Temporary Items folder is invisible to the user. 


text style table In an item color table resource, a 
specification for the typeface, font style, font size, 
and color of text in an editable text item or a 
static text item. 


title bar The bar at the top of a window that 
displays the window name, contains the close 
and zoom boxes, and indicates whether the 
window is active. 


Toolbox Event Manager See Event Manager. 


Trash folder A directory at the root level of a 
volume for storing files that the user has moved 
to the Trash icon. After opening the Trash icon, 
the user sees the collection of all items that the 
user has moved to the Trash icon—that is, the 
union of appropriate Trash directories from 

all mounted volumes. A Macintosh computer 
set up to share files among users in a network 
environment maintains separate Trash 
subdirectories for remote users within its shared 
Trash directory. The Finder empties a Trash 
directory (or, in the case of a file server, a Trash 
subdirectory) only when the user of that 
directory chooses the Empty Trash command. 


update event An event indicating that the 
contents of a window need updating. 


update region A region maintained by the 
Window Manager that includes the parts of a 
window’s content region that need updating. 
The Event Manager generates update events 

as necessary, based on the contents of the 

update region, telling your application to update 
a window. 
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user state The size and location that the user 
has established for a window. 


variation code A number that selects among 
variations supported by a single window 
defintion function or control definition function. 
The variation code is stored in the low-order 4 
bits of the window definition ID or control 
definition ID. See also control definition 
function, control definition ID, window 
definition function, and window definition ID. 


virtual key code A value that represents the 
key pressed or released by the user; this value is 
always the same for a specific physical key on a 
keyboard. Compare character code. 


visible region The part of a window’s graphics 
port that’s actually visible on the screen—that is, 
the part that’s not covered by other windows. 


window An area on the screen that displays 
information, including user documents as well 
as communications such as alert boxes and 
dialog boxes. The user can open or close a 
window; move it around on the desktop; and 
sometimes change its size, scroll through it, and 
edit its contents. 


window color table The data structure in 
which the Window Manager stores the colors 
to be used for drawing a window’s frame and 
for highlighting selected text. 


window definition function A function that 
defines the general appearance and behavior of a 
window. The Window Manager calls the window 
definition function to draw the window’s frame, 
determine what region of the window the cursor 
is in, draw the window’s size box, draw the 
window’s zoom box, move and resize the 
window, and calculate the window’s structure 
and content regions. 


window definition ID An integer that specifies 
the resource ID of a window definition function 
in the upper 12 bits and an optional variation 
code in the lower 4 bits. When creating a new 
window, your application supplies a window 
definition ID either as a field in the 'WIND' 
resource or as a parameter to the NewWindow or 
NewCWindow function. 
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window list A list maintained by the Window 
Manager of all windows on the desktop. The 
frontmost window is first in the window list, and 
the remaining windows appear in the order in 
which they are layered on the desktop. 


Window Manager port A graphics port that 
represents the desktop area on the main 
monitor—that is, a rounded-corner rectangle that 
occupies all of the main monitor except for the 
area occupied by the title bar. 


window origin The upper-left corner of a 
window. Usually specified as (0,0), the window 
origin is expressed in coordinates local to 

the window. 


window record A data structure of type 
WindowRecord (or CWindowRecord) in which 
the Window Manager stores a window’s charac- 
teristics, including the window’s graphics port, 
title, visibility status, and control list. 


window region Special-purpose region of a 
window. See also close region, content region, 
drag region, size region, and zoom region. 


window type A collection of characteristics— 
such as the shape of the window’s frame and the 
features of its title bar—that describe a window. 


zoom box A box in the right side of a window’s 
title bar that the user can click to alternate 
between two different window sizes (the user 
state and the standard state). 


zoom region The area occupied by a window’s 
zoom box. See also zoom box. 
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AEProcessAppleEvent function 2-68, 2-78 
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Alert function 6-106 to 6-108 
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alias files 7-39 
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"ALRT' resource type. See alert resources 
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ANumber global variable 6-172 
‘appe' file type 7-44 
AppendDITL procedure 6-54, 6-125 to 6-127 
AppendMenu procedure 3-64 to 3-67, 3-124 to 3-125 
AppendResMenu procedure 3-20, 3-68 to 3-70, 3-128 to 
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Apple Event Interprocess Messaging Protocol 
(AEIMP) 2-13, 2-67 
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defined 2-13 
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as high-level events 2-67 to 2-69 
Open Documents 7-20 
sending 2-78 
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Apple menu 3-20 
About command 3-21 to 3-22, 3-45 
accessing from dialog boxes 6-68 to 6-73 
adding items to 3-68 to 3-69 
creating 3-43 to 3-44 
handling 3-80 to 3-81 
Apple Menu Items folder 
adding items from, to Apple menu 3-20 to 3-21 
alias type for 7-40 
defined 7-43 
finding 7-54 
"APPL' file type 7-10 
application-defined items 
creating 6-56 to 6-61 
specifying in alert or dialog boxes 6-29 to 6-30, 6-155 
application heap 2-32 
application icons. See also icon families 
creating 7-10 to 7-17 
default 7-12 
Application menu 3-33 
accessing from alert and dialog boxes 6-68 to 6-69 
Hide Others command. 3-33 
application-missing message string resources 7-27 to 
7-30, 7-68 to 7-69 
applications 
alias type for 7-40 
in Apple Menu Items folder 7-43 
creating icons for 7-11 to 7-17 
default icon for 7-12 
launching from the Finder 7-25 to 7-26 
sharing 2-68 
signatures for 7-8 to 7-10 
switching between 2-5 
application-unavailable alert box messages 7-27 to 7-30 
arrow cursor 2-63 
arrows, in scroll bars. See scroll arrows 
'x***" file type 7-20 
AtMenuBottom global variable 3-151 
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auto-key events 2-38 

auto-key threshold rate 2-38 

A/UX and cancel events 2-46 

AuxCt1Rec data type 5-76 to 5-77, 5-107 
auxiliary control records 5-76 to 5-77, 5-107 
auxiliary window record 4-21, 4-73 to 4-74 
AuxWinRec data type 4-73 to 4-74 
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background applications, and Extensions folder 7-44 
background processes 2-4 
Balloon Help online assistance, for icons 7-38. See also 
help balloons 
BeginUpdate procedure 2-47, 4-50, 4-106 to 4-107 
"BNDL' resource type 7-20 to 7-25, 7-65 to 7-68 
BringToFront procedure 4-90 
bundle bit 7-34 
bundle resources 7-20 to 7-25, 7-45, 7-65 to 7-68 
Button function 2-108 
buttons 
active 5-11 to 5-13 
control definition ID for 5-14 
creating, in windows 5-17 to 5-20 
default 6-10 to 6-11, 6-22, 6-30 to 6-31, 6-56 to 6-61 
defined 5-5 
events in 5-31 to 5-37, 6-78 
inactive 5-11 to 5-13 
part code for 5-32 
specifying in alert or dialog boxes 6-29 to 6-30, 6-153 
titles for 6-37 to 6-39 
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CalcMenuSize procedure 3-143, 5-28 
CalcVisBehind procedure 4-119 
CalcVis procedure 4-119 
canBackground flag 2-117 
cancel events 2-46 to 2-47 
Can’t Undo command (Edit menu) 3-24, 3-25 
Caps Lock key 2-20 
caret, time between blinks of 2-113 
catalog files 
defined 7-5 
Finder information in 7-32 to 7-34, 7-46 to 7-51 
CautionAlert function 6-111 
caution alerts 
creating with the CautionAlert function 6-111 
defined 6-9 
"cctb' resource type 5-121 to 5-123 
'CDEF' resource type 5-14, 5-109 to 5-115 
character codes 2-40 
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checkboxes 
active 5-11 to 5-13 
changing setting and display of 5-38 to 5-39 
control definition ID for 5-14 
defined 5-5 to 5-6 
events in 6-78 
in windows 5-31 to 5-32, 5-38 to 5-39 
inactive 5-11 to 5-13 
part code for 5-32 
specifying in alert or dialog boxes 6-29 to 6-30, 6-153 
CheckItem procedure 3-61 to 3-62, 3-136 
CheckUpdate function 4-116 
"cicn' resource type 7-64 
specifying a menu item’s 3-62, 3-154 
Clear command (Edit menu) 3-25, 6-69 
ClearMenuBar procedure 3-110 
ClipAbove procedure 4-116 to 4-117 
Clipboard 3-24 
converting data to and from 2-58 to 2-60 
Hide Clipboard command (Edit menu) 3-25 
Show Clipboard command (Edit menu) 3-25 
close box 4-6 
Close command (File menu) 3-23 
CloseDialog procedure 6-119 to 6-120 
close region 4-12 
CloseWindow procedure 4-60, 4-104 to 4-105 
closing windows 4-60 to 4-62 
routines for 4-103 to 4-106 
"CNTL"' resource type 
example of 5-18, 5-21, 5-23, 5-26 
Rez input format for 5-18 to 5-24, 5-25 to 5-28 
Rez output format for 5-118 to 5-121 
Color control panel 4-20, 4-65 
color flag 7-48 
color graphics ports 4-20 
color icon resources 3-46, 3-62, 7-64 
color icons 7-11, 7-13 to 7-16 
Color QuickDraw 
checking for 
when creating a window 4-77 
when zooming windows 4-54 
and color window records 4-65 
coordinate systems in 4-17 to 4-18 
creating color windows 4-20 to 4-21 
and the Window Manager port 4-74 
colorReserved flag 7-48 
colors 
in alert boxes and dialog boxes 6-156 to 6-164 
in controls 5-5 
Label menu commands for 7-16 
in menus 3-46, 3-62, 3-98 to 3-102 
in windows 4-20 to 4-21 
ColorSpec data type 4-72, 5-78 to 5-79 
color window records 4-65 to 4-68 
Command key 2-20 


Command-key equivalents. See keyboard equivalents 
Command-Shift-number key sequences 2-39, 2-86 
content region 
defined 4-6, 4-12 
drawing 4-39 to 4-40 
updating 4-40 to 4-41, 4-48 to 4-50 
context of a process, switching 2-15 to 2-16 
control color table records 5-77 to 5-80 
control color table resources 5-121 to 5-123 
control color tables 6-160 to 6-162 
control definition functions 
custom 5-109 to 5-115 
defined 5-14 
for pop-up menus 5-14, 5-36 
standard 5-14 
control definition IDs 
for buttons 5-14 
for checkboxes 5-14 
for custom controls 5-109 to 5-110 
defined 5-14 
for pop-up menus 5-14 
for radio buttons 5-14 
for scroll bars 5-14 
specifying 5-18, 5-19, 5-25, 5-83 to 5-84, 5-120 
Control key 2-20 
control list 4-14 
Control Manager 5-3 to 5-135 
application-defined routines for 5-109 to 5-117 
data structures in 5-72 to 5-80 
and Dialog Manager 5-3, 5-5, 5-16, 5-29, 5-31, 6-78 
and Event Manager 5-3 
and List Manager 5-3 
localization guidelines 5-15, 5-19 to 5-20, 5-85, 5-120 
and Resource Manager 5-3 
resources for 5-117 to 5-123. See also control color 
tables; control definition functions; control 
resources; 
routines in 5-80 to 5-117 
user interface guidelines 5-5 to 5-13, 5-52 to 5-53 
and Window Manager 5-3 
control panels, installing and removing 7-41 
Control Panels folder 
alias type for 7-40 
defined 7-43 
finding 7-54 
Cont rolRecord data type 5-73 to 5-75 
control records 5-73 to 5-75 
control resources 
example of 5-18, 5-21, 5-23, 5-26 
Rez input format for 5-18 to 5-24, 5-25 to 5-28 
Rez output format for 5-118 to 5-121 
controls 
action procedures for 5-91, 5-102, 5-115 to 5-117 
activating 5-13 
active 5-11 to 5-13, 6-13 
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in alert and dialog boxes 6-29 to 6-30, 6-154 
colors in 5-5, 5-101, 5-121 to 5-123 
control definition IDs for 5-18, 5-19, 5-25, 5-83 to 
5-84, 5-120 
custom. See custom controls 
defined 5-3 
dragging 5-35, 5-99 to 5-100, 5-114 to 5-115 
drawing 5-17, 5-85 to 5-88 
events in 5-88 to 5-93, 6-78 
highlight states of 5-35, 5-98 to 5-99 
inactive 5-13, 6-13, 6-74 
indicators in. See indicators, in controls 
invisible 5-18, 5-19, 5-25, 5-83, 5-97, 5-119 
mouse events in 5-11 to 5-13, 5-30 to 5-70 
moving 5-65 to 5-70, 5-97 to 5-98 
part codes for 5-31 to 5-32 
pop-up menus 6-42 to 6-44 
rectangles for 5-18 to 5-19, 5-22 to 5-23, 5-25 to 5-26, 
5-82, 5-118. See also display rectangles 
reference values for 
changing 5-105 to 5-106 
determining 5-105 
specifying 5-18, 5-25, 5-84, 5-120 
removing 5-108 to 5-109 
resizing 5-65 to 5-70, 5-98 
resources for. See control resources 
settings of 
changing 5-11, 5-37 to 5-43, 5-61, 5-65 to 5-70, 5-93 
to 5-102 
determining 5-37 to 5-43, 5-102 to 5-107 
specifying initial 5-18 to 5-19, 5-21 to 5-23, 5-25 to 
5-28, 5-83, 5-118 to 5-119 
standard 5-4, 5-15 to 5-28, 5-81 to 5-85 
text in 5-18, 5-19 to 5-20, 5-25 
titles of 
changing 5-96 
determining 5-104 to 5-105 
specifying 5-18, 5-19 to 5-20, 5-25, 5-83, 5-85, 
5-120, 5-121 
types of 5-4 to 5-13. See also buttons; checkboxes; 
custom controls; pop-up menus; radio buttons; 
scroll bars 
updating 5-29 to 5-30 
visible 5-18, 5-19, 5-25, 5-83, 5-119 
in windows 4-14 to 4-15, 4-23, 5-82 
cooperative multitasking 2-10 
coordinate systems 4-17 to 4-18 
Copy command (Edit menu) 3-25, 6-69 
CountDITL function 6-128 
CountMItems function 3-81, 3-141 
Create Publisher command (Edit menu) 3-25 
creators 
assigning 7-33 to 7-34, 7-47 to 7-49 
defined 7-9 to 7-10 
Ct1CTab data type 5-77 to 5-80 
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‘ctr1' folder type 7-54 
current menu list 3-40 
current process 2-28 
cursors 
adjusting 2-65 to 2-67 
arrow 2-63 
cross 2-63 
I-beam 2-63 
plus 2-63 
setting the appearance of 2-62 
wristwatch 2-63 
custom alert boxes 
creating with the Alert function 6-106 to 6-108 
defined 6-9 
custom controls 5-11, 5-109 to 5-115 
customized icons 7-17 to 7-18 
Cut command (Edit menu) 3-25, 6-69 
CWindowPeek data type 4-65 
CWindowPtr data type 4-65 
CWindowRecord data type 4-65 to 4-68 
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DABeeper global variable 6-172 
DASt rings global variable 6-172 
data forks 1-11 
dBoxProc window type 2-16, 4-9, 6-25 
"dctb' resource type 6-156 to 6-157 
default buttons 6-10 to 6-11, 6-22, 6-30 to 6-31, 6-56 to 
6-61 
DeleteMCEntries procedure 3-147 
DeleteMenuItem procedure 3-127 to 3-128 
DeleteMenu procedure 3-109 to 3-110 
DelMCEnt ries procedure. See DeleteMCEntries 
procedure 
DelMenuItem procedure. See DeleteMenuItem 
procedure 
desk accessories 
handling events in 2-36, 2-87, 2-95 
and System 7 7-13 
desk accessory resource. See 'DRVR' resource type 
"desk! folder type 7-54 
DeskHook global variable 4-75 
DeskPattern global variable 4-113 
desktop 7-3 
desktop database 7-5, 7-45 to 7-46 
Desktop file 7-5 
Desktop Folder 
defined 7-43 
finding 7-54 
Desktop Manager 7-45 
desktop objects 3-20 
desktop pattern 4-112 
dial controls 5-11 
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dialog boxes 
accessing menus from 3-84, 6-68 to 6-73 
alert boxes, as distinguished from 6-6 to 6-8 
closing 6-100 to 6-101 
creating 6-23 to 6-26, 6-113 to 6-119 
default colors of, changing 6-156 to 6-157 
defined 6-5 
displaying 6-61 to 6-75 
disposing of 6-113, 6-119 to 6-120 
event filter function for 6-86 to 6-89 
events in 2-25, 2-29 to 2-30, 6-82 to 6-100, 6-135 to 
6-143 
examples of 1-9 
items in. See items in alert and dialog boxes 
types of 6-9 to 6-12 
as windows 6-15 to 6-17 
window types for 4-9 to 4-10 
dialog color table resources 6-75, 6-156 to 6-157 
DialogCopy procedure 6-133 
DialogCut procedure 6-132 to 6-133 
DialogDelete procedure 6-134 
Dialog Manager 6-5 to 6-172 
application-defined routines for 6-143 to 6-147 
and Control Manager 5-3, 5-5, 5-16, 5-29, 5-31, 6-78 
data structures in 6-101 to 6-102 
initializing 6-102 to 6-105 
localization guidelines for 6-34 to 6-35, 6-39, 6-40, 
6-80, 6-130 
and Menu Manager 6-68 to 6-73 
resources in 6-147 to 6-164. See also alert color table 
resources; alert resources; dialog color table 
resources; dialog resources; item color table 
resources; item list resources 
routines in 6-102 to 6-147 
testing for availability of AppendDITL, 
ShortenDITL, and CountDITLroutines 6-18 
and TextEdit 6-79 to 6-80 
user interface guidelines for 6-8 to 6-12, 6-31 to 6-34, 
6-37 to 6-41, 6-42, 6-62 to 6-64 
and Window Manager 4-13 to 4-14, 6-15 to 6-16 
DialogPaste procedure 6-133 to 6-134 
DialogPeek data type 6-102 
DialogPtr data type 6-102 
DialogRecord data type 6-101 to 6-102 
dialog records 6-101 to 6-102 
dialog resources 
defined 6-15 
example of 6-24 
Rez input format for 6-24 to 6-26 
Rez output format for 6-148 to 6-149 
DialogSelect function 2-29, 6-80, 6-89 to 6-93, 6-139 
to 6-141 
DIBadMount function 2-56 
DInfo data type 7-50 
directories, finding system-related 7-53 to 7-56 
directory information record 7-50 


disabled constant 3-8 
disabled items 6-13 
DisableItem procedure 3-58 to 3-59, 3-131 to 3-132 
‘disk' file type 7-20 
disk-inserted events 
in alert and dialog boxes 6-87 
handling 2-55 to 2-56 
and the ModalDialog procedure 2-56 
and standard file dialog boxes 2-55 
disks, opening 7-20 
display rectangles, for items in alert and dialog 
boxes 6-29, 6-32 to 6-35 


DisposDialog procedure. See DisposeDialog 
procedure 
DisposeControl procedure 5-108 
DisposeDialog procedure 6-120 
DisposeMCInfo procedure 3-145 
DisposeMenu procedure 3-140 
DisposeWindow procedure 4-105 to 4-106 
DITLMethod data type 6-51, 6-166 
'DITL' resource type. See item list resources 
dividers 3-12 
DlgCopy procedure. See DialogCopy procedure 
DlgCut procedure. See DialogCut procedure 
DlgDelete procedure. See DialogDelete procedure 
DlgFont global variable 6-172 
DlgPaste procedure. See DialogPaste procedure 
"DLOG' resource type. See dialog resources 
documentP roc window type 4-10 
documents 5-9 to 5-10, 5-43 to 5-70 
creating icons for 7-16 to 7-17, 7-17 to 7-18 
creators of 7-9 to 7-10 
default icon for 7-12 
file types of 7-9 to 7-10, 7-18 to 7-20 
opening from the Finder 7-25 to 7-26 
prohibiting users from opening from Finder 7-30 
window types for 4-8 
document windows 
defined 4-4 
positioning 4-30 
saving position of 4-34 
window types for 4-8 
doesActivateOnFGSwitch flag 2-117 
double clicks, time between 2-38, 2-113 
DragControl procedure 5-99 to 5-100 
DragGrayRgn function 4-96 to 4-98 
DragHook global variable 4-98, 4-100, 4-102, 4-104 
drag region 4-12 
DragWindow procedure 4-44, 4-94 to 4-95 
DrawControls procedure 5-87 to 5-88 
DrawDialog procedure 6-142 
DrawGrowlIcon procedure 4-12, 4-39, 4-86 to 4-87 
DrawMenuBar procedure 3-51, 3-58, 3-113 
DrawNew procedure 4-117 











DispMCInfo procedure. See DisposeMCInfo procedure 
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DrawlControl procedure 5-88 

‘drop! alias type 7-40 

drop folder, alias type for 7-40 

"DRVR' resource type 3-20, 3-68, 3-129, 3-130 
DXInfo data type 7-50 to 7-51 


E 


editable text items 
events in 6-79 to 6-80 
getting text from 6-48 to 6-51, 6-130 to 6-131 
highlighting default text in 6-131 to 6-132 
setting text in 6-131, 6-153 
specifying in dialog boxes 6-29 to 6-30, 6-153 
Edition Manager 2-14 
editions 
creating icons for 7-16 
defined 7-4 
Edit menu 3-24 to 3-26 
accessing from alert and dialog boxes 6-68 to 6-73 
adjusting 3-75 to 3-77 
Can’t Undo command 3-25 
Clear command 3-25, 6-69 
Copy command. 3-25, 6-69 
Create Publisher command 3-25 
Cut command 3-25, 6-69 
Hide Clipboard command 3-25 
Paste command. 3-25, 6-69 
Publisher Options command 3-25 
Select All command. 3-25 
Show Clipboard command 3-25 
Subscriber Options command 3-25 
Subscribe To command 3-25 
Undo command 3-25, 6-69 
8-bit color icons 7-11 
‘empt ' folder type 7-54 
enabled constant 3-8 
enabled items 6-13 
EnableItem procedure 3-58 to 3-59, 3-131 
EndUpdate procedure 2-47, 2-49, 4-50, 4-107 
EraseRect procedure 4-103 
ErrorSound procedure 6-104 
EventAvail function 2-21, 2-88 to 2-89 
event classes 2-68 
event filter functions 6-86 to 6-89, 6-145 to 6-147 
event IDs 2-68 
event loops 2-24 to 2-25 





Event Manager 2-3 to 2-132. See also Operating System 


Event Manager 
application-defined routine for 2-114 to 2-115 
and Control Manager 5-3 
data structures in 2-79 to 2-83 
initializing 2-17 
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and MultiFinder 2-7 
and the PPC Toolbox 2-7, 2-13 
and the Process Manager 2-5 
routines in 2-84 to 2-113 
and the Scrap Manager 2-60 
testing for features 2-17 
event masks 
defined 2-22, 2-85 
setting 2-26 to 2-29 
event messages 2-19, 2-80 
event queue. See also high-level event queue; Operating 
System event queue 
scanning for a cancel event in 2-46 
structure of 2-83 
EventRecord data type 2-79 to 2-81 
event records 2-79 to 2-81 
defined 2-4 
and event loops 2-25 
for high-level events 2-68, 2-69 
events 
activate 2-8, 2-50 to 2-55, 4-50 to 4-53 
in alert boxes 2-29 to 2-30, 6-81 to 6-82, 6-86 to 6-89, 
6-135 
Apple. See Apple events 
auto-key 2-8, 2-38 
in buttons in windows 5-31 to 5-37 
cancel 2-46 to 2-47 
in checkboxes in windows 5-38 to 5-39 
Command-period 2-46 
in controls 5-11 to 5-13, 5-30 to 5-70, 5-88 to 5-93, 6-78 
defined 2-4 
in desk accessories 2-36 
in dialog boxes 2-29 to 2-30, 6-77 to 6-100, 6-135 to 
6-143 
disk-inserted 2-8, 2-55 to 2-56 
in editable text items 6-79 to 6-80 
filter function for, in alert and dialog boxes 6-86 to 
6-89, 6-145 to 6-147 
first click in an inactive window 4-42 
getting information about 2-18 to 2-21 
in gray areas of scroll bars 5-57 to 5-61 
handling 2-26 
high-level. See high-level events 
interacting with the user from the background 2-12 
keyboard 2-8, 2-38 to 2-45 
key-down 2-38 
key-up 2-38, 2-39 
low-level 2-8 to 2-9 
masking out 2-27 
events (continued) 
in modal dialog boxes 6-82 to 6-89, 6-135 to 6-137 
in modeless dialog boxes 2-25, 6-89 to 6-100, 6-138 to 
6-141 
and modifier keys 2-20 to 2-21, 2-34 
mouse-down 2-8, 2-33 to 2-38 
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mouse-down in windows 4-42 to 4-45 
mouse-moved 2-12, 2-23, 2-62 to 2-67 
mouse-up 2-8, 2-33 


in movable modal dialog boxes 6-89 to 6-100, 6-138 


to 6-141 
null 2-9, 2-57 
operating-system 2-10 to 2-12, 2-58 to 2-67 
in pop-up menus 6-42 
in windows 5-31 to 5-37 
priority of 2-15 
processing 2-21 to 2-30 
in radio buttons in windows 5-31 to 5-32 
received in the background 2-12 
receiving from other applications 2-69 to 2-71 
resume 2-12, 2-60 to 2-62 
in scroll arrows 5-57 to 5-61 
in scroll bars 5-43 to 5-65 
in scroll boxes 5-53 to 5-57 
sources of 2-6 
suspend 2-12, 2-60 to 2-62 
switching contexts 2-15 to 2-16 
types of 2-5, 2-18, 2-79 
update 2-9, 2-47 to 2-50, 4-48 to 4-50 
in windows 4-21 to 4-22, 4-41 to 4-53 
event types 2-5, 2-18, 2-79 
EVQE1 data type 2-83 
exported AppleShare folder, alias type for 7-40 
extended directory information record 7-50 to 7-51 
extended file information record 7-49 
Extensions folder 
alias type for 7-40 
defined 7-44 
finding 7-54 
‘extn ' folder type 7-54 
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'faam' alias type 7-40 
"fact ' alias type 7-40 
'fadr' alias type 7-40 
'faet' alias type 7-40 
'faex' alias type 7-40 
'famn' alias type 7-40 
'fapf' alias type 7-40 
'fapn' alias type 7-40 
'fash' alias type 7-40 
'fast' alias type 7-40 
'fasy' alias type 7-40 
'fdrp' alias type 7-40 
'ff£il' file type 7-37 

file information record 7-34, 7-47 to 7-49 
File menu 3-22 to 3-24 

Close command 3-23, 7-18 


New command 3-23 

Open command. 3-23 

Page Setup command 3-23 

Print command 3-23 

Quit command 3-23, 7-18 

Save As command. 3-23 

Save command. 3-23 
file reference resources 7-18 to 7-25, 7-64 to 7-65 
files. See also applications; documents 

data fork of 1-11 

managing 1-15 

resource fork of 1-11 

temporary 7-43 

user comments associated with 7-45 
file types 

for alias files 7-40 

‘appe' 7-33, 7-47 

"APPL' 7-10 

assigning 7-9 to 7-10, 7-33 to 7-34, 7-47 to 7-49 

VkKKKKS 7-20 

defining in file reference resources 7-18 to 7-25 

"'DFIL' 7-37 

"disk' 7-20 

'FFIL' 7-37 

"ffil' 7-37 

"fold' 7-20 

"ifil' 7-37 

"kfil' 7-37 

for movable resources 7-37 

opening documents of particular 

from applications 7-10 
from the Finder 7-25 to 7-26 





'222?' 7-20 
"scri' 7-44 
"sfil' 7-37 
for stationery pads 7-19 
"tfil' 7-37 


filter function. See also event filter functions 
for GetSpecificHighLevelEvent 2-92 to 2-93, 
2-114 to 2-115 
FindControl function 5-33 to 5-35, 5-44, 5-53 to 5-54, 
5-58, 5-89 to 5-90 
FindDialogItem function 6-125 
FindDItem function. See FindDialogItem function 
Finder 
application interface to 7-3 to 7-78 
database for a volume 7-45 to 7-46 
data structures used by 7-46 to 7-51 
defined 7-3 to 7-5 
Finder (continued) 
and Process Manager 7-25 
relation to File Manager 7-3 
and Resource Manager 7-3 
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resources used by 7-6 to 7-32, 7-56 to 7-70. See also 
application-missing message string resources; 
bundle resources; file reference resources; icon 
list resources; large 8-bit color icon resources; 
large 4-bit color icon resources; missing- 
application name string resources; signature 


resources; small 8-bit color icon resources; small 


4-bit color icon resources; small icon list 
resources; version resources 
routines for 7-51 to 7-56 
user interface guidelines for 7-13, 7-15 
Finder flags 7-33 to 7-34, 7-47 to 7-48 


Finder information, in the catalog file 7-32 to 7-34, 7-46 


to 7-51 
FindFolder function 7-54 to 7-56 
FindWindow function 4-12, 4-44, 4-91 to 4-93, 5-32 to 
5-33 

and activate events 2-51 

and mouse events 2-33 to 2-37, 4-42 to 4-44 
FInfo data type 7-34, 7-47 to 7-49 
“first click” in an inactive window 4-7, 4-42 
'FKEY' resource type 2-39, 2-86, 3-118 
FlashMenuBar procedure 3-141 to 3-142 
'fld#' resource type 7-55 
floppy disks, alias type for 7-40 
'flpy' alias type 7-40 
FlushEvents procedure 2-93 to 2-94 
folder resources 7-55 
folders 

alias type for 7-40 

finding system-related 7-53 to 7-56 
folder types 7-54 
'fold' file type 7-20 
'FOND' resource type 3-69 
"font ' folder type 7-54 
Font menu 3-26 to 3-27, 3-69 to 3-70 
font resources 

icon for 7-37 to 7-38 

installing and removing 7-41 
'FONT' resource type 3-69 
fonts 

bitmapped 3-27 

suitcases for 7-37 

TrueType 3-27 
Fonts folder 7-44 
foreground process 2-4 
4-bit color icons 7-11 
frames, window 4-6, 4-12 to 4-13 
'FREF' resource type 7-18 to 7-25, 7-64 to 7-65 
FrontWindow function 4-93 to 4-94 
FSpGetFInfo function 7-34, 7-49 
FSpSetFInfo function 7-34, 7-49 
FXInfo data type 7-49 





ge 
Ge 


tAlertStage function 6-66, 6-112 

tAlrtStage function. See GetAlert Stage function 
tAuxCt1 function. See 
GetAuxiliaryControlRecord function 
tAuxiliaryControlRecord function 5-107 
tAuxWin function 4-115 to 4-116 

tCaretTime function 2-113 

tControlAction function 5-106 
tControlMaximum function 5-41 to 5-42, 5-61, 5-104 
tControlMinimum function 5-103 to 5-104 
tControlReference function 5-105 
tControlTitle procedure 5-104 to 5-105 
tControlValue function 5-38 to 5-39, 5-41 to 5-42, 
5-44, 5-53 to 5-55, 5-61, 5-103 
tControlVariant function 5-106 to 5-107 
tCRefCon function. See Get Cont rolReference 
function 

tCTitle procedure. See GetControlTitle 
procedure 

tCtlAction function. See GetControlAction 
function 

tCt1Max function. See Get Cont rolMaximum function 
tCt1Min function. See GetCont rolMinimum function 
tCt1Value function. See Get Cont rolValue function 
tCVariant function. See GetControlVariant 
function 

tCWMgrPort procedure 4-113 to 4-114 

tDb1Time function 2-113 

tDialogItem procedure 6-50, 6-121 to 6-122 
tDialogItemText procedure 6-50, 6-130 to 6-131 
tDItem procedure. See GetDialogItem procedure 
tEvQHdr function 2-100 

tFrontClicks flag 2-118 

tGray function 3-91 

tGrayRgn function 4-113 

tItemCmd procedure 3-138 to 3-139 

tItemIcon procedure 3-137 

tItemMark procedure 3-135 

t Item procedure. See GetMenuItemText procedure 
tItemStyle procedure 3-133 to 3-134 

tIText procedure. See GetDialogItemText 
procedure 

tKeys procedure 2-110 

tMBarHeight function 3-113 

tMCEntry function 3-145 to 3-146 

tMCInfo function 3-52, 3-143 to 3-144 

tMenuBar function 3-112 

tMenu function 3-55, 3-106 to 3-108 








MenuHandle function 3-122 

MenulItemText procedure 3-80, 3-132 

MHandle function. See GetMenuHand1le function 
Mouse procedure 2-108 
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GetNewControl function 5-15 to 5-18, 5-24 to 5-25, 
5-81 to 5-82 
GetNewCWindow function 4-28, 4-76 to 4-77 
GetNewDialog function 6-113 to 6-115 
GetNewMBar function 3-50 to 3-52, 3-111 to 3-112 
GetNewWindow function 4-28, 4-78 to 4-79 
GetNextEvent function 2-21, 2-89 to 2-90 
GetOSEvent function 2-97 to 2-98 
GetPortNameF romP rocessSerialNumber 
function 2-107 
GetProcessInformation function 2-74 
GetProcessSerialNumberFromPortName 
function 2-73, 2-82, 2-106 
Get SpecificHighLevelEvent function 2-71, 2-77, 
2-92 to 2-93 
GetWindowPic function 4-110 
GetWMgrPort procedure 4-114 
GetWRefCon function 4-111 
GetWTitle procedure 4-86 
GetWVariant function 4-24, 4-112 
global coordinates 4-17 
GlobalToLocal procedure 5-34 
graphics ports 4-17 to 4-18 
gray areas, in scroll bars 

action procedures for 5-58 to 5-61 

defined 5-9 

events in 5-57 to 5-61 

part codes for 5-32 
gray region 4-16 
GrayrRgn global variable 4-16, 4-95, 4-113, 4-116 
grow images, of windows 4-57, 4-87 
GrowWindow function 4-57 to 4-59, 4-99 to 4-100 
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hard disks, alias type for 7-40 
hasBeenInited flag 7-48 
hasBundle flag 7-34 
hasCustomicon flag 7-17 to 7-18, 7-34 
hasNoINITS flag 7-48 
"hdsk' alias type 7-40 
help balloon resources 3-44, 3-68 
help balloons 
for icons 7-38 
for window frames 4-23 
help items, specifying in alert or dialog boxes 6-29 to 
6-30, 6-155 to 6-156 
Help menu 3-29 to 3-31 
accessing from alert and dialog boxes 6-68 to 6-69 
adding items to 3-67 to 3-68 
handling 3-81 
Hide Balloons command 6-68 
Show Balloons command 6-68 


Hide Balloons command (Help menu) 6-68 
Hide Clipboard command (Edit menu) 3-25 
HideControl procedure 5-39 to 5-40, 5-65 to 5-67, 5-97 
HideDialogItem procedure 6-123 to 6-124 
HideDItem procedure. See HideDialogItem procedure 
Hide Others command (Application menu) 3-33 
HideWindow procedure 4-61, 4-89 
hierarchical menus 3-38, 3-53 to 3-56 
high-level event message record 2-72, 2-82 to 2-83 
HighLevelEventMsg data type 2-72, 2-82 
high-level event queue 2-7, 2-13 
high-level events 2-13 to 2-15, 2-67 to 2-78. See also 
Apple events 

accepting 2-69, 2-70 

defined 2-13 

determining the sender of 2-72 

event classes 2-68 

event IDs 2-68 

handling 2-67 to 2-78 

posting options 2-75 

receiving 2-68, 2-87 

replying to 2-74 

and return receipts 2-77 

searching for a specific event 2-71 to 2-72, 2-92 

sending 2-73 to 2-77, 2-101 

supporting 2-25 

testing for availability 2-7 
HiliteControl procedure 5-98 to 5-99, 6-13 to 6-14, 
6-50 to 6-51, 6-74, 6-98 
HiliteMenu procedure 3-71, 3-79, 3-119 to 3-120 
HiliteWindow procedure 4-90 
HiWord function 4-58 
HMGet HelpMenuHandle function 3-67 to 3-68, 3-81, 
3-123 to 3-124 
"hmmu' resource type 3-44, 3-68 
HMSetMenuResID procedure 6-71 
hot spot 2-62 
human interface guidelines. See user interface 

guidelines 
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I-beam cursor 2-63 
"icl8"' resource type 

creating 7-11, 7-24 

Rez output format for 7-61 to 7-62 
"icl4' resource type 

creating 7-11, 7-24 

Rez output format for 7-59 to 7-60 
'ICN#' resource type 

creating 7-11 to 7-15 

example of 7-14 to 7-15 

Rez output format for 7-57 to 7-58 
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specifying in a bundle resource 7-20 
icon families 7-11 
icon list resources 

creating 7-11 to 7-15 

example of 7-14 to 7-15 

Rez output format for 7-57 to 7-58 

specifying in bundle resources 7-20 
icon masks 7-13, 7-15 
icon resources ('ICON' resource type) 7-63 
"ICON' resource type 7-63 

specifying a menu item’s 3-46, 3-62, 3-154 
icons. See also icon families 

for applications 7-10 to 7-15 

black and white 7-13, 7-15 

color 7-15 to 7-16 

creating 7-11 to 7-18 

customizing 7-17 to 7-18 

defaults used by Finder 7-12, 7-40 

defined 7-3 

for documents 7-16 to 7-18 

for editions 7-16 

8-bit color 7-11 

for font resources 7-37 

4-bit color 7-11 

for keyboard layout resources 7-37 

large 7-10, 7-13 

for menu items 3-62 to 3-64 

in menus 3-12, 3-62 to 3-64, 3-154 

for query documents 7-16 

reduced 3-62 to 3-63 

for script system resource collections 7-37 

small 7-13, 7-15 

for sound resources 7-37 

specifying in alert or dialog boxes 6-29 to 6-30, 6-154 

for stationery pads 7-16, 7-19, 7-36 

system 7-12 

for TrueType font resources 7-37 
"ics8' resource type 

creating 7-11, 7-24 

Rez output format for 7-62 to 7-63 
"ics4' resource type 

creating 7-11, 7-24 

Rez output format for 7-60 to 7-61 
‘ics#' resource type 

creating 7-11, 7-15, 7-24 

Rez output format for 7-58 to 7-59 
"ictb' resource type 6-158 to 6-164 
‘ifil' file type 7-37 
inactive controls 5-13, 6-13 to 6-14 
inactive windows 4-6 to 4-7 

handling mouse-down events in 4-43 
indicators, in controls 

defined 5-11 

dragging 5-35, 5-99 to 5-100, 5-114 to 5-115 
Info box. See information windows 
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information windows 
using the stationery checkbox in 7-34 
using to customize icon 7-17 
version information in 7-8, 7-32 
InitDialogs procedure 6-103 to 6-104 
‘INIT’ file type 7-44 
InitMenus procedure 3-103 to 3-104 
InitProcMenu procedure 3-104 
InitWindows procedure 4-75 
input methods 3-32 
InsertMenuItem procedure 3-64 to 3-67, 3-126 to 3-127 
InsertMenu procedure 3-55, 3-108 to 3-109 
InsertResMenu procedure 3-69, 3-129 to 3-130 
InsMenuItem procedure. See InsertMenulItem 
procedure 
InvalMenuBar procedure 3-114 
InvalRect procedure 4-107 to 4-108 
InvalRgn procedure 4-59, 4-108 
IPCListPorts function 2-74 
isAlias flag 7-40 
IsDialogEvent function 2-29, 6-77, 6-138 to 6-139 
isHighLevelEventAware flag 2-119 
isInvisible flag 7-34 
isOnDesk flag 7-48 
isShared flag 7-34, 7-48 
isStationeryAware flag 2-119 
isStationery flag 7-34 
is32BitCompatible flag 2-118 
item color table resources 6-158 to 6-164 
item list resources 
counting items in 6-128 
defined 6-13 
example of 6-27 to 6-28 
Rez input format for 6-26 to 6-30 
Rez output format for 6-151 to 6-156 
specifying for a dialog box 6-24 
specifying for an alert box 6-20 
item numbers 6-28 
items in alert and dialog boxes. See also 
application-defined items; buttons; checkboxes; 
controls; editable text items; icons; item list 
resources; pictures; pop-up menus; radio 
buttons; static text items 
adding 6-51 to 6-56, 6-125 to 6-127 
copying editable text from 6-133 
counting 6-128 
creating 6-26 to 6-44 
cutting editable text from 6-132 to 6-133 
default colors of, changing 6-158 to 6-164 
defined 6-13 
deleting editable text from 6-134 
display rectangles for 6-29, 6-32 to 6-35 
drawing application-defined 6-143 to 6-144 
enabled and disabled 6-13, 6-36 
finding item numbers of 6-125 
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getting handles to 6-121 to 6-122 
getting text strings from 6-130 to 6-131 
hiding 6-123 to 6-124 
highlighting default text in 6-131 to 6-132 
item numbers for 6-28 
keyboard navigation 6-44 
manipulating 6-44 to 6-56, 6-120 to 6-128 
pasting editable text into 6-133 to 6-134 
pictures 6-29 to 6-30 
redisplaying after hiding 6-124 
removing 6-127 to 6-128 
setting or changing 6-122 to 6-123 
setting text strings in 6-131 
substituting text in 6-129 to 6-130 
types of 6-13 to 6-14, 6-30 

'itlc' resource type 3-32, 3-33 

'it1k' resource type 2-41 
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"KCHR' resource type 2-39 to 2-42, 3-17 
keyboard equivalents 3-18 to 3-19 
commonly used 3-19 
defining 3-47 
reserved 3-18 
keyboard events 
in alert boxes 6-86 to 6-89 
in dialog boxes 6-79 to 6-80, 6-86 to 6-89, 6-94 to 6-97 
handling 2-38 to 2-45 
in windows 4-47 
keyboard layout resources 2-39 to 2-42, 3-17, 3-32, 3-33 
Keyboard menu 3-32 to 3-33 
accessing from alert and dialog boxes 6-68 to 6-69 
added by Menu Manager 3-19 
keyboard resources 
icon for 7-37 to 7-38 
"KCHR' 2-39 to 2-42 
"KMAP' 2-21, 2-39 to 2-42 
keyboards 2-40 
Apple Extended Keyboard II, domestic 2-43 
Apple Extended Keyboard II, ISO 2-43 
Apple Keyboard II, ISO 2-42 
getting the state of 2-110 
key-down events 
defined 2-8 
handling keyboard equivalents 3-77 to 3-78 
receiving 2-38 to 2-46 
KeyMap data type 2-110 
KeyTrans function. See KeyTranslate function 
KeyTranslate function 2-110 to 2-111, 3-78 
key-up events 2-8, 2-29 
"kfil' file type 7-37 
KillControls procedure 5-108 to 5-109 


"KMAP' resource type 2-21, 2-39 to 2-42 
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Label menu commands 7-16 
large 8-bit color icon resources 
creating 7-11, 7-24 
Rez output format for 7-61 to 7-62 
large 4-bit color icon resources 
creating 7-11, 7-24 
Rez output format for 7-59 to 7-60 
large (32-by-32 pixel) icons 7-10, 7-11 
launching applications, from the Finder 7-25 to 7-26 
listings. See sample routines 
List Manager, and Control Manager 5-3 
localAndRemoteHLEvents flag 2-119 
local coordinates 4-18 
local IDs 
in bundle resources and file reference resources 7-19, 
7-22, 7-24 
for mapping resources 7-18 to 7-25 
localization guidelines 
for Control Manager 5-15, 5-19 to 5-20, 5-85, 5-120 
for Dialog Manager 6-34 to 6-35, 6-39, 6-40, 6-80, 
6-130 
location names 2-73, 2-75 
low-level events 
handling 2-32 to 2-57 
receiving 2-21 
LoWord function 4-58 
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Macintosh Toolbox 
features provided by 1-4 
introduction to 1-3 to 1-16 
"macs ' folder type 7-54 
major switches 2-16 
marking character in a menu item 3-12 
masks 
event. See event masks 
icon 7-13, 7-15 
MBarEnable global variable 3-121 
"MBAR' resource type 3-50, 3-155 
'MBDF' resource type 3-9, 3-87, 3-104 
MCEntry data type 3-99 
MCTable data type 3-99 
MCTableHandle data type 3-99 
'mctb' resource type 3-52, 3-99, 3-143, 3-155 to 3-157 
'"MDEF' resource type 3-87, 3-157 
memory, allocating 1-15 
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menu bars 
accessing from alert and dialog boxes 6-68 to 6-73 
creating 3-49 to 3-50 
defined 3-6, 3-10 
handling mouse-down events in 3-72 
installing 3-41 
menu bar definition function 3-9, 3-87, 3-104 
MenuChoice function 3-118 to 3-119 
menu color information table 3-52, 3-98 to 3-102 
menu bar entry 3-100 
menu item entry 3-101 
menu title entry 3-101 
resources 3-155 to 3-157 
menu commands. See also menu items 
About (Apple menu) 3-21 
Can’t Undo (Edit menu) 3-25 
for changing colors in the Finder 7-16 
Clear (Edit menu) 3-25, 6-68 to 6-69 
Close (File menu) 3-23 
Copy (Edit menu) 3-25, 6-68 to 6-69 
Create Publisher (Edit menu) 3-25 
Cut (Edit menu) 3-25, 6-68 to 6-69 
Hide Balloons (Help menu) 6-68 
Hide Clipboard (Edit menu) 3-25 
Hide Others (Application menu) 3-33 
keyboard equivalents for 3-16 to 3-19, 3-154 
New (File menu) 3-23 
None (Color menu) 7-16 
Open (File menu) 3-23 
Other (Size menu) 3-28 
Page Setup (File menu) 3-23 
Paste (Edit menu) 3-25, 6-68 to 6-69, 7-17 
Print (File menu) 3-23 
Publisher Options (Edit menu) 3-25 
Quit (File menu) 3-23 
Save (File menu) 3-23 
Save As (File menu) 3-23 
Select All (Edit menu) 3-25 
Show Balloons (Help menu) 3-30, 6-68 
Show Clipboard (Edit menu) 3-25 
Subscriber Options (Edit menu) 3-25 
Subscribe To (Edit menu) 3-25 
Undo (Edit menu) 3-25, 6-68 to 6-69 
menu definition procedure 3-148 to 3-151 
and the A5 register 3-150 
defined 3-9 
drawing color menus 3-91 
handling scrolling in menus 3-91, 3-93 
standard 3-148 
writing 3-87 to 3-95 
menu handle 3-95, 3-122 
MenuHandle data type 3-95 
menu ID 3-40, 3-152 
MenuInfo data type 3-96 to 3-97 
menu items 3-12 to 3-16 
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in an accumulating group 3-15 
adding to Apple menu 3-68 to 3-69 
adding to Help menu 3-67 to 3-68 
adding to menus 3-64 to 3-70 
appearance of 3-12 to 3-14 
changing 
font style of 3-60 
icon of 3-62 to 3-64 
mark of 3-61 to 3-62 
script code of 3-62 
text of 3-59 to 3-60 
characteristics of 3-12 to 3-14 
disabling 3-8, 3-58 to 3-59, 3-74 to 3-77 
divider 3-12 
enabling 3-8, 3-58 to 3-59, 3-74 to 3-77 
font style of 3-47, 3-154 
grouping 3-14 to 3-16 
handling user selection of 3-70 to 3-78 
icon of 3-154 
item numbers 3-40 
keyboard equivalents for 3-16 to 3-19, 3-154 
marking character of 3-154 
metacharacters in 3-65 
in a mutually exclusive group 3-14 
providing help balloons for 3-7 
script code of 3-47, 3-62, 3-154 
script of 3-12 
specifying the characteristics of 3-45 to 3-47 
submenu for 3-47, 3-154 
terms to use in help balloons and user 
documentation 3-8 
text of 3-12 to 3-13 
MenuKey function 3-71, 3-77 to 3-78, 3-117 to 3-118 
menu lists 3-40, 3-97 to 3-98 
Menu Manager 3-5 to 3-167 
application-defined routines for 3-148 to 3-151 
data structures in 3-95 to 3-102 
data structures maintained by 3-40 to 3-41 
and Dialog Manager 6-68 to 6-73 
initializing 3-103 to 3-104 
localization guidelines for 3-10, 3-16 to 3-18, 3-43 
routine names, mapping of 3-102 
routines in 3-102 to 3-147 
testing for availability 3-42 
user interface guidelines for 3-5 to 3-38 
menu records 3-40, 3-95 to 3-97 
menu resource 3-151 to 3-154 
"MENU ' resource type 3-42 to 3-48, 3-152 to 3-154 
menus. See also Apple menu; Application menu; Edit 
menu; File menu; Font menu; Help menu; 
Keyboard menu; Size menu; Style menu 
accessing from alert and dialog boxes 3-84 to 3-86, 
6-68 to 6-73 
adding items to 3-64 to 3-70 
adjusting items in 3-73 to 3-77 
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Apple. See Apple menu 
Application. See Application menu 
color 3-11 
creating 3-42 to 3-57, 3-105 to 3-108 
hierarchical 3-53 to 3-56 
pop-up 3-56 to 3-57, 5-25 to 5-28, 6-42 to 6-44 
pull-down 3-42 to 3-56 
disabling for alert and dialog boxes 6-68 to 6-73 
disposing of 3-112, 3-140 
Edit. See Edit menu 
File. See File menu 
Font. See Font menu 
grouping items in 3-14 to 3-16 
Help. See Help menu 
help balloons for 3-31 
hierarchical 3-6, 3-38, 3-53 to 3-56 
items in. See menu items 
Keyboard. See Keyboard menu 
keyboard equivalents for 3-16 to 3-19, 3-154 
localizing 3-10 
menu ID 3-152 
pop-up. See pop-up menus 
pull-down 3-6, 3-42 
resource ID 3-44, 3-153 
Size. See Size menu 
Style. See Style menu 
submenus 3-6, 3-53 to 3-56 
system-handled 3-19 
titles of 3-7, 3-10 
types of 3-6 
MenuSelect function 3-8, 3-70, 3-72, 3-73, 3-78 to 3-79, 
3-115 to 3-117 
message string resources 7-27 to 7-30 
minor switches 2-16 
missing-application name string resources 7-27 to 7-30, 
7-68 
modal dialog boxes 
accessing menus from 6-68 to 6-73 
closing 6-100 to 6-101 
creating 6-23 to 6-26, 6-113 to 6-119 
defined 6-10 to 6-11 
displaying 6-61, 6-62 to 6-75 
event filter function for 6-86 to 6-89, 6-145 to 6-147 
events in 6-82 to 6-86, 6-135 to 6-137 
window types for 4-9 
ModalDialog procedure 6-84, 6-135 to 6-137 
and disk-inserted events 2-56 
and menus 3-86 
modeless dialog boxes 
accessing menus from 6-68 to 6-73 
closing 6-100 to 6-101 
creating 6-23 to 6-26, 6-113 to 6-119 
defined 6-12 
displaying 6-61 to 6-67 
events in 6-89 to 6-100, 6-138 to 6-141 


titles for 6-25 

window types for 4-10 
modifier keys 2-20 to 2-21, 2-81, 3-77 
mounted folder, alias type for 7-40 
mouse 

determining location of 2-108 

getting information about 2-108 
mouse-down events 

in alert boxes 6-78, 6-81 to 6-82 

in controls 5-11 to 5-13, 5-30 to 5-70 

in desk accessories 2-87, 2-95 

in dialog boxes 6-78 to 6-80, 6-82 to 6-94 

handling 2-33 to 2-38 

in the menu bar 3-72 to 3-73 

in windows 4-42 to 4-45 
mouse driver 2-62 
mouse-moved events 2-23, 2-62 to 2-67, 2-86 
mouse region 2-23, 2-64 to 2-67 
mouse-up events 2-33 

in alert boxes 6-78, 6-81 to 6-82 

in controls 5-11 to 5-13, 5-30 to 5-70 

in dialog boxes 6-78 to 6-80, 6-82 to 6-94 
movableDBoxProc window type 3-85, 4-9, 6-25 
movable modal dialog boxes 

accessing menus from 6-68 to 6-73 

closing 6-100 to 6-101 

creating 6-23 to 6-26, 6-113 to 6-119 

defined 6-11 to 6-12 

displaying 6-61, 6-62 

events in 6-89 to 6-100, 6-138 to 6-141 

titles for 6-25 

window types for 4-9 
movable resources 7-36 to 7-38 
MoveCont rol procedure 5-67 to 5-70, 5-97 to 5-98 
MoveWindow procedure 4-95 to 4-96 
MultiFinder 2-7 
MyAction procedure 5-116 to 5-117 
MyAlertSound procedure 6-144 to 6-145 
MyControl function 5-110 to 5-115 
MyEventFilter function 6-145 to 6-147 
MyIndicatorAction procedure 5-117 
MyItem procedure 6-143 to 6-144 
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nameLocked flag 7-18, 7-34 

name string resources for applications 7-27 to 7-30 
networks, using shared Trash directories on 7-44 
NewCDialog function. See NewColorDialog function 
NewColorDialog function 6-115 to 6-118 

New command (File menu) 3-23 

NewControl function 5-82 to 5-85 

NewCWindow function 4-79 to 4-82 
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NewDialog function 6-118 to 6-119 
NewMenu function 3-105 to 3-106 
NewWindow function 4-82 to 4-85 
noGrowDocProc window type 4-10, 6-25 
NoteAlert function 6-110 
note alerts 
creating with the NoteAlert function 6-110 
defined 6-8 
Notification Manager, and operating-system 
events 2-12 
null events 
defined 2-9 
and event masking 2-28 
handling 2-57 


O 


OldContent global variable 4-117 
Oldstructure global variable 4-117 
onlyBackground flag 2-117 
Open command (File menu) 3-23 
OpenDeskAcc function 3-21, 3-80 to 3-81 
Open Documents events 7-20, 7-25 to 7-26 
opening 

applications, from the Finder 7-25 to 7-26 

disks 7-20 

documents 7-25 to 7-26 

folders 7-20 
Operating System Event Manager 2-3, 2-7. See also 

Event Manager 

Operating System event queue 

defined 2-6 

flushing events from 2-93 
operating-system events 

defined 2-10 to 2-12 

handling 2-58 to 2-67 
Option key 2-20 
OSEventAvail function 2-98 to 2-99 
Other command (Size menu) 3-28 to 3-29, 3-82 to 3-84 
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page regions, in scroll bars. See gray areas 
Page Setup command (File menu) 3-23 
PaintBehind procedure 4-118 to 4-119 
PaintOne procedure 4-118 

PaintWhite global variable 4-118, 4-119 
Palette Manager, and system color tables 4-21 
ParamText procedure 6-47, 6-129 to 6-130 
part codes 5-31 to 5-32 

partitions, sizes of 2-30, 2-115 
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Paste command (Edit menu) 
and dialog boxes 6-69 
and information windows 7-17 
introduced 3-25 
PBGetCatInfo function 7-34, 7-49 
PBMountVol function 2-55 
pCDeskPat parameter-RAM bit flag 4-113 
pictures, in alert or dialog boxes 6-29 to 6-30, 6-154 
PinRect function 4-99 
plainDBoxProc window type 4-9 
pop-up menus 3-33 to 3-38 
action procedure for 5-36 to 5-37 
active 5-11 to 5-13 
control definition function for 3-33, 3-34 to 3-36, 5-14 
control definition ID for 5-14 
creating 3-56 to 3-57, 5-25 to 5-28 
defined 3-6, 5-6 to 5-7 
in dialog boxes 6-42 to 6-44 
events in, in windows 5-31 to 5-37 
inactive 5-11 to 5-13 
testing for availability 3-42 
type-in fields 3-37 
variation codes for 5-27 to 5-28 
PopUpMenuSelect function 3-57, 3-120 to 3-121 
popupPrivateData data type 5-77 
port names 2-75 
converting to process serial numbers 2-105 
and receiving high-level events 2-73 
port rectangle 4-18, 4-101, 4-103 
of Window Manager port 4-75 
PostEvent function 2-104 to 2-105 
PostHighLevelEvent function 2-73 to 2-77, 2-101 to 
2-103 
posting options 2-75 
PPCBrowser function 
filling in a target ID record 2-77 
finding a specific port 2-75 
posting a high-level event 2-74 to 2-75 
PPC (Program-to-Program Communications) 
Toolbox 1-16, 2-7 
PPostEvent function 2-103 to 2-104 
preferences files 7-43 
Preferences folder 
alias type for 7-40 
defined 7-43 
finding 7-54 
storing files in 7-43 
"pref ' folder type 7-54 
Print command (File menu) 3-23 
Print Documents events 7-25 to 7-26 
PrintMonitor Documents folder 
alias type for 7-40 
defined 7-44 
finding 7-54 
"prnt ' folder type 7-54 
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processes 
background 2-4 
context of 2-15 
foreground 2-4 
switching between 2-5, 2-15 
Process Manager 
and Event Manager 2-3 
and the Finder 7-25 
process serial numbers, converting to port 
names 2-105 to 2-107 
Program-to-Program Communications (PPC) 
Toolbox 1-16, 2-7 
Publisher Options command (Edit menu) 3-25 
pull-down menus 
creating 3-43 to 3-52 
defined 3-6 
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QHdr data type 2-83 
query documents 
creating icons for 7-16, 7-17 
default icon for 7-12 
defined 7-4 
QuickDraw 1-14. See also Color QuickDraw 
coordinate systems in 4-17 to 4-18 
Quit command (File menu) 3-23 
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radio buttons 
active 5-11 to 5-13 
control definition ID for 5-14 
creating, in windows 5-20 to 5-21 
defined 5-6 
events in 6-78 
in windows 5-31 to 5-32 
inactive 5-11 to 5-13 
part code for 5-32 
specifying in alert or dialog boxes 6-153 
rDocProc window type 4-10 


rectangles, for controls 5-18 to 5-19, 5-25 to 5-26, 5-82, 


5-118. See also display rectangles 

refCon field 4-111 
reference values 

changing, for controls 5-105 to 5-106 

determining, for controls 5-105 

for pop-up menus 5-28 

specifying, for controls 5-18, 5-25, 5-84, 5-120 
region codes, in version resources 7-31 
requiresSwitchLaunch flag 7-48 


Rescued Items from volume name folders 7-44 
ResetAlertStage procedure 6-112 
ResetAlrt Stage procedure. See ResetAlertStage 
procedure 
resizing windows 4-57 to 4-59 
ResolveAliasFile function 7-52 to 7-53 
resource forks 1-11 
resource IDs 
for cursors 2-63 
defined 1-11 
for icons in menu items 3-62 
Resource Manager 1-11 to 1-13 
and Control Manager 5-3 
and the Finder 7-3 
resource maps 1-12 
resources 1-11 to 1-13 
alert 6-19 to 6-22, 6-150 to 6-151 
alert color table 6-157 to 6-158 
alias record 7-40 
application-missing message string 7-68 to 7-69 
bundle 7-20 to 7-25, 7-65 to 7-68 
color icon 3-62, 7-64 
control 5-18 to 5-28, 5-118 to 5-121 
control color table 5-121 to 5-123 
control definition function 5-14, 5-109 to 5-115 
defined 1-11 
dialog 6-15, 6-24 to 6-26, 6-148 to 6-149 
dialog color table 6-75 to 6-76, 6-156 to 6-157 
driver 3-20, 3-68, 3-129, 3-130 
file reference 7-18 to 7-25, 7-64 to 7-65 
folder 7-55 
font 3-69 
resources (continued) 
font family 3-69 
icon 3-62, 7-63 
icon list 7-13, 7-57 to 7-58 
international configuration 3-32 
item color table 6-158 to 6-164 
item list. See item list resources 
keyboard-layout 2-39 
key-map 2-39, 2-41, 2-42 
key-remap 2-39, 2-41 
large 8-bit color icon 7-61 to 7-62 
large 4-bit color icon 7-59 to 7-60 
menu 3-151 to 3-154 
menu bar 3-155 
menu bar definition function 3-9, 3-87, 3-104 
menu color information table 3-155 to 3-157 
menu definition procedure 3-157 
missing-application name string 7-68 
movable 7-36 to 7-38 
signature 7-8 to 7-10 
size 2-115 to 2-119, 7-35 
small 8-bit color icon 7-62 to 7-63 
small 4-bit color icon 7-60 to 7-61 
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small icon 3-62 resume events 

small icon list 7-58 to 7-59 defined 2-10 

sound 7-37 to 7-38 handling 2-60 to 2-62 

string 3-60 ResumeProc global variable 6-172 
string list 3-60, 3-65 to 3-67 return receipts 2-75, 2-77 

System file, in the 1-12 RGBColor data type 5-79 


used by the Finder 7-6 to 7-32 
version 7-31 to 7-32, 7-69 to 7-70 
window 4-22, 4-25 to 4-27, 4-124 to 4-127 
































window color table 4-127 to 4-129 S 
window definition function 4-22, 4-120, 4-127 
resource types 1-11 sample code. See sample routines 
"actb' 6-157 to 6-158 sample routines 
"alis' 7-40 DisplayMyDialog 6-58 
"ALRT'. See alert resources DoActivate 2-53, 4-51 to 4-52 
"BNDL' 7-20 to 7-25, 7-65 to 7-68 DoActivateGlobalChangesDialog 6-98 
"cctb' 5-121 to 5-123 DoCloseCmd 4-60 to 4-61, 6-94 
"CDEF' 5-14, 5-109 to 5-115 DoContentClick 5-33, 5-53, 6-92 
"cicn' 3-62, 3-154, 7-64 DoCopyResource 7-29 
"CNTL' 5-18 to 5-28, 5-118 to 5-121 DoDiskEvent 2-56 
"dctb' 6-156 to 6-157 DoDrumRol1CheckBox 5-38 
"DITL'. See item list resources DoEvent 2-26, 3-72, 3-77 
"DLOG'. See dialog resources DoGlobalChangesDialog 6-67 
"DRVR' 3-20, 3-68, 3-129, 3-130 DoGraphicsScroll 5-47 
"FKEY' 2-39, 3-118 DoGrowWindow 4-58 to 4-59 
"fld#' 7-55 DoHighLevelEvent 2-70 
"FOND! 3-69, 3-129, 3-130 DoIdle 2-57, 6-79 
"FONT! 3-69, 3-129, 3-130 DoKeyDown 2-44, 3-78, 6-95 
'FREF' 7-18 to 7-25, 7-64 to 7-65 DoMenuCommand 3-79 
"hmmu' 3-44, 3-68 DoMouseDown 2-34, 3-72, 4-44 to 4-45, 5-32, 6-91 
"icl8' 7-61 to 7-62 DoNew 5-24 
"icl4' 7-59 to 7-60 DoNewCmd 4-28 to 4-29 
"ICN#' 7-20, 7-57 to 7-58 sample routines (continued) 
"ICON' 3-62, 3-154, 7-63 DoOpenFile 4-37 to 4-38 
‘ics8' 7-62 to 7-63 DoOSEvent 2-59 
‘ics4' 7-60 to 7-61 DoPlayButton 5-36 
‘ics#' 7-15, 7-58 to 7-59 DoPopUpMenu 5-37 
"ictb' 6-158 to 6-164 DoSaveAsCmd 7-28 
‘itlc' 3-32 DoShowModelessFindDialogBox 4-64 
"itlk' 2-41 DoSpel1BoxWithSpanish 6-54 
"KCHR' 2-39 to 2-42 DoSuspendResumeEvent 2-61 
"KMAP' 2-39 to 2-42 DoUpdate 2-50, 4-50, 5-29, 5-62, 6-99 
"MBAR' 3-155 DoZoomWindow 4-55 to 4-56 
"MBDE' 3-9, 3-87, 3-104 IsStationeryDoc 7-36 
"mctb' 3-155 to 3-157 MyAddHelpItem 3-68 
"MDEF' 3-157 MyAdjustCursor 2-65 
"MENU! 3-151 to 3-154 MyAdjustEditMenuForDocWindow 3-75 
"SICN' 3-62, 3-154 MyAdjustEditMenuForModalDialogs 6-72 
"SIZE' 2-115 to 2-119, 7-35 MyAdjustFileMenuForDocWindow 3-74 
"STR ' 3-60, 7-27 to 7-30 MyAdjustHv 5-41 
"STR#' 3-60, 3-65 to 3-67 MyAdjustMenus 3-73, 6-70 
"vers' 7-31 to 7-32, 7-69 to 7-70 MyAdjustMenusForDialogs 6-70 
"wetb' 4-127 to 4-129 MyAdjustScrollBars 5-39 
"WDEF' 4-22, 4-120, 4-127 MyAdjustScrollSizes 5-67 
"WIND' 4-22, 4-25 to 4-27, 4-124 to 4-127 MyAdjustScrollValues 5-40 
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MyAlert 6-66 
MyAlertSound 6-22 
MyChangeMenuBarAndSaveColorInfo 3-52 
MyCloseDocument 4-61 to 4-62, 6-47 
MyCreateP laySoundsWindow 5-17 
MyDrawDefaultButtonOutline 6-59 
MyDrawGraphicsWindow 5-63 
MyDrawWindow 4-39, 5-30, 5-65 
MyEventFilter 6-88 
MyEventLoop 2-24 
MyGetLocalUpdateRgn 4-60 
MyGetWindowType 4-24 
MyHandleAppleCommand 3-80 
HandleHelpCommand 3-81 
HandleKeyDown 2-44, 6-95 
HandleKeyDownInModeless 6-96 
HandleModelessDialogs 6-49 
HandleSizeCommand 3-83 
HorzntlActionProc 5-59 
MakeAllMenus 3-70 
MakeMenus 3-50 
MakeSubMenu 3-55 
MDEF 3-89 
MoveScrollBox 5-61 
MyOpen 7-41 
MyPostTest 2-74 
MyPostWithPPCBrowser 2-76 
MyResizeWindow 4-59 
MySaveWindowPosition 4-34 to 4-35 
MySetWindowPosition 4-36 to 4-37 
MySpellCheckDialog 6-83 
MyToggleHideShow 3-59 
MyVerticalActionProc 5-59 
ShowMyAboutBox 6-65 
UserDidCancel 2-46 
Save As command (File menu) 3-23 
Save command (File menu) 3-23 
SaveOld procedure 4-117 
SaveUpdate global variable 4-118 
SaveVisRgn global variable 4-106 
scrap 

converting global to private 2-12 

converting private to global 2-12 
scrap coercion 2-58, 2-61 
Scrap Manager 1-14, 2-60 
"scri' file type 7-44 
script, changing a menu item’s 3-62, 3-154 
script code, for menu item text 3-47, 3-62 
script system resource collections, icon for 7-37 
scroll arrows 

action procedures for 5-58 to 5-61 

defined 5-8 to 5-9 

events in 5-57 to 5-61 

part codes for 5-32 
scroll bars. See also gray areas; scroll arrows; scroll boxes 














'Y 
'Y 
'Y 
'Y 
'Y 
'Y 
'Y 
'Y! 
'Y! 
'Y! 
'Y! 
'Y! 





activating 5-13 
active 5-11 to 5-13 
changing settings and display of 5-9 to 5-10, 5-39 to 


5-43, 5-44, 5-61, 5-70 


control definition ID for 5-14 

creating, in windows 5-21 to 5-25 

defined 5-7 to 5-10 

document scrolling with 5-9 to 5-10, 5-43 to 5-70 

events in 5-31 to 5-32, 5-43 to 5-65 

inactive 5-11 to 5-13 

and List Manager 5-3 

moving and resizing 5-65 to 5-70 

updating 5-30 

as a window element 4-6 
scroll boxes 

action procedure for 5-36 

defined 5-7 to 5-8 

dragging 5-35 

events in 5-53 to 5-57 

moving 5-9 to 5-10, 5-39 to 5-43, 5-44, 5-61, 5-70 

part code for 5-32 
ScrollRect procedure 5-46 to 5-48, 5-56 to 5-57 
Select All command (Edit menu) 3-25 
SelectDialogItemText procedure 6-131 to 6-132 
SelectWindow procedure 2-51, 4-87 to 4-88 
SelIText procedure. See SelectDialogItemText 


procedure 


SendBehind procedure 4-91 
servers, alias type for 7-40 
session reference number 2-73 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


Se 


tControlAction procedure 5-102 

tControlColor procedure 5-101 

tControlMaximum procedure 5-41 to 5-43, 5-70, 5-95 
to 5-96 
tControlMinimum procedure 5-95 
tControlReference procedure 5-105 to 5-106 
tControlTitle procedure 5-96 

tControlValue procedure 5-38 to 5-39, 5-42 to 5-43, 
5-44, 5-61, 5-94 to 5-95 

tCRefCon procedure. See SetControlReference 
procedure 

tCTitle procedure. See SetControlTitle 
procedure 

tCtlAction procedure. See SetControlAction 
procedure 

tCt1Color procedure. See SetControlColor 
procedure 

tCt1Max procedure. See SetControlMaximum 
procedure 

tCt1Min procedure. See SetControlMinimum 
procedure 

tDAFont procedure. See SetDialogFont procedure 
tDeskCPat procedure 4-112 to 4-113 

tDialogFont procedure 6-105 

tDialogItem procedure 6-122 to 6-123 
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SetDialogItemText procedure 6-131 

SetDItem procedure. See SetDialogItem procedure 
SetEventMask procedure 2-99 to 2-100 

Set ItemCmd procedure 3-139 to 3-140 
SetItemIcon procedure 3-62 to 3-64, 3-137 to 3-138 
Set ItemMark procedure 3-61 to 3-62, 3-135 to 3-136 
Set Item procedure. See SetMenuItemText procedure 
SetItemStyle procedure 3-60, 3-134 

Set IText procedure. See SetDialogItemText 
procedure 

SetMCEntries procedure 3-146 to 3-147 
SetMCInfo procedure 3-52, 3-144 

SetMenuBar procedure 3-50 to 3-51, 3-112 to 3-113 
SetMenuF lash procedure 3-142 

SetMenuItemText procedure 3-59 to 3-60, 3-133 
SetOrigin procedure 5-44 to 5-45, 5-63 to 5-64 
SetPort procedure 6-62 

SetWinColor procedure 4-114 to 4-115 
SetWindowPic procedure 4-110 

SetWRefCon procedure 4-111 

SetWTitle procedure 4-85 

'sfil' file type 7-37 

shared folder, alias type for 7-40 

Shift key 2-20 

ShortenDITL procedure 6-127 to 6-128 

Show Balloons command (Help menu) 6-68 

Show Clipboard command (Edit menu) 3-25 








howDialogItem procedure 6-124 


howHide procedure 4-89 to 4-90 
howWindow procedure 4-88, 6-61 
"SICN' resource type, specifying a menu item’s 3-62, 
3-154 

signature resources 7-8 to 7-10 
signatures 

in bundle resources 7-20 

as creators 7-9 

defined 7-8 

registering 7-8 to 7-10 
16-by-16 pixel (small) icons 7-11, 7-15 
size box 4-6 
SizeControl procedure 5-67 to 5-70, 5-98 
Size menu 3-27 to 3-29, 3-82 

handling 3-82 to 3-84 

Other command in 3-28 to 3-29 
size region 4-12 
size resources 2-115 to 2-119, 7-35 
"SIZE" resource type 2-115 to 2-119, 7-35 
creating 2-30 to 2-32 
defined 2-30 to 2-32, 2-115 to 2-119 
flags, defined 2-116 to 2-119 
and null events 2-9, 2-57 
sample Rez input 2-31 
scheduling option flags 2-16 
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‘S) 
S 
ShowDItem procedure. See ShowDialogItem procedure 
S 
S 


setting flags for high-level events 2-68 
setting flags of 2-9, 2-11, 2-16, 2-51 
SizeWindow procedure 4-60, 4-101 
sleep value 2-22 
slider controls 5-11 
small 8-bit color icon resources 
creating 7-11, 7-24 
Rez output format for 7-62 to 7-63 
small 4-bit color icon resources 
creating 7-11, 7-24 
Rez output format for 7-60 to 7-61 
small icon list resources 
creating 7-11, 7-15, 7-24 
Rez output format for 7-58 to 7-59 
small (16-by-16 pixel) icons 
resource IDs for 7-15 
resources for 7-10 
sound resources 
icon for 7-37 to 7-38 
installing and removing 7-41 
'srvr' alias type 7-40 
stack, size of 2-32 
standard control definition function 5-14 
standard file dialog boxes, and disk-inserted 
events 2-55 
Standard File Package, and disk-inserted events 2-55 
to 2-56 
standard state of a window 4-33, 4-53, 4-70 
Startup Items folder 
alias type for 7-40 
defined 7-44 
finding 7-54 
static text items 
getting text from 6-130 to 6-131 
setting text in 6-36 to 6-41, 6-131, 6-153 
specifying in alert or dialog boxes 6-29 to 6-30, 6-153 
substituting text in 6-46 to 6-48 
substituting text strings in 6-129 to 6-130 
user interface guidelines for 6-40 to 6-41 
stationery pads 
creating icons for 7-16, 7-19 
default icon for 7-12 
defined 7-4, 7-34 to 7-36 
recognition of 2-119 
StillDown function 2-109 
StopAlert function 6-109 
stop alerts 
creating with the StopAlert function 6-109 
defined 6-9 
"STR ' resource type 3-60, 7-27 to 7-30 
'STR#' resource type 3-60, 3-65 to 3-67 
"strt' folder type 7-54 
structure region 4-6, 4-12 
Style data type 3-134 
StyleItem data type 3-134 


INDEX 


Style menu 3-15 
example of 3-15 
and the Font menu 3-27 
keyboard equivalents for 3-19 
styles 
changing a menu item’s 3-47, 3-60 
of amenu item 3-12 
submenus 
creating 3-53 to 3-56 
defined 3-6 
Subscriber Options command (Edit menu) 3-25 
Subscribe To command (Edit menu) 3-25 
suitcases for fonts and desk accessories 7-37 
suspend events 
defined 2-10 
handling 2-60 to 2-62 
switching 
context 2-15 
major 2-16 
minor 2-16 
system alert sounds 6-8, 6-22 
SystemClick procedure 2-87, 2-94 to 2-95, 4-43, 4-44 
system color tables, and Palette Manager 4-21 
SystemEdit function 3-122 
SystemEvent function 2-96 
system event masks 2-28 to 2-29, 2-99 
system extensions 
and Extensions folder 7-44 
installing and removing 7-41 
System file 7-44 
System Folder 
alias type for 7-40 
defined 7-5 
finding 7-54 
organization of 7-41 to 7-45 
system-handled menus 3-19 
SystemMenu procedure 3-121 
SystemTask procedure 2-25, 2-87, 2-95 to 2-96 





T 


Target ID data type 2-72, 2-81 
target ID records 2-81 to 2-82 

receiving 2-73 

sending 2-75 
"temp! folder type 7-54 
temporary files 7-43, 7-44 
Temporary Items folder 

defined 7-43 

finding 7-54 
EPinScroll procedure 5-55 to 5-56 
TestControl function 5-93 
EUpdate procedure 5-64 to 5-65 














t 


ext 
in buttons, checkboxes, and radio buttons 5-18, 5-19, 
5-19 to 5-20, 5-25, 6-37 to 6-40, 6-153 
editable, in dialog boxes. See editable text items 
handling 1-14 to 1-15 
static, in alert and dialog boxes. See static text items 


TextEdit 


and Dialog Manager 6-79 to 6-80 
handling text 1-14 to 1-15 
and mouse events 2-37 


'TEXT' file type 7-10 


t 





ext style table 6-160, 6-162 to 6-164 


32-by-32 pixel (large) icons 7-11, 7-13 


t 


humb controls. See scroll boxes 
[TickCount function 2-112 





t 
t 


Ticks global variable 2-112 
itle bar 4-5 
itles 
of buttons, checkboxes, and radio buttons 6-37 to 
6-40, 6-153 
changing, for controls 5-96 
determining, for controls 5-104 to 5-105 
for modeless and movable modal dialog boxes 6-25 
specifying for controls 5-18, 5-19 to 5-20, 5-25, 5-83, 
5-85, 5-120, 5-121 


Toolbox Event Manager. See Event Manager 


[opMenulItem global variable 3-151 
[TrackBox function 4-44, 4-101 to 4-102 
[TrackControl function 5-35 to 5-37, 5-44, 5-53 to 5-55, 
5-58, 5-90 to 5-92, 6-78 
and pop-up menus 3-56 





[TrackGoAway function 4-44, 4-103 to 4-104 


Trash, alias type for 7-40 
Trash directories 


appearance to users 7-42 
defined 7-44 
finding 7-54 


'trsh' alias type 7-40 
‘trsh' folder type 7-54 
TrueType fonts 7-37. See also fonts 


U 


Undo command (Edit menu) 3-25, 6-69 
UpdateControls procedure 5-86 to 5-87 
UpdateDialog procedure 6-142 to 6-143 
update events 4-13 


in alert boxes 6-82, 6-86 to 6-89 

defined 2-9 

in dialog boxes 6-85, 6-86 to 6-89, 6-97 to 6-100 
handling 2-47 to 2-50, 4-48 to 4-50 

routines for handling 4-106 to 4-107 

for windows 4-41 
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update region 
defined 4-13 
maintaining 4-41 
redrawing 4-40 to 4-41 
UpdtControl procedure. See UpdateControls 
procedure 


UpdtDialog procedure. See UpdateDialog procedure 


user interface guidelines 

for Control Manager 5-52 to 5-53 

for controls 5-5 to 5-13 

for Dialog Manager 6-8 to 6-12, 6-31 to 6-34, 6-37 to 

6-41, 6-42, 6-62 to 6-64 

for icons 7-13, 7-15 

for static text items 6-40 to 6-41 

for windows 4-5 to 4-7, 4-21, 4-30 to 4-32 
user-oriented design 1-5 
user state of awindow 4-33, 4-53, 4-70 
useTextEditServices flag 2-119 





V 


ValidRect procedure 4-58, 4-108 to 4-109 
ValidRgn procedure 4-109 
variation codes 
for controls, defined 5-14 
determining, for controls 5-106 to 5-107 
for windows 4-11, 4-112, 4-120 
version information for applications 
in Finder windows 7-31 
in information windows 7-32 
in signature resource 7-8 
in 'vers' resource 7-31 to 7-32 
version resources 7-31 to 7-32, 7-69 to 7-70 
"vers ' resource type 7-31 to 7-32, 7-69 to 7-70 
virtual key codes 2-40 
of Apple Extended Keyboard II, domestic 2-43 
of Apple Extended Keyboard II, ISO 2-43 
of Apple Keyboard II, ISO 2-42 
visible region 4-48 
volume catalogs, Finder information in 7-32 to 7-34 
volumes, Finder’s desktop database for 7-45 


W, X, Y 


WaitMouseUp function 2-109 
WaitNextEvent function 2-85 to 2-88 
introduced 2-22 to 2-24 
and multitasking 2-60 
"wetb' resource type 4-71, 4-127 to 4-129 
"WDEF' resource type 4-22, 4-120, 4-127 
WinCTab data type 4-71 to 4-72 
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window color table 4-21, 4-71 to 4-73 
window definition functions 
defined 4-10 
writing 4-120 to 4-124 
window definition IDs 
creating windows, used in 4-80, 4-83 to 4-84 
defined 4-11 
for a dialog box 6-25 
and window definition functions 4-120 
in window resources 4-26, 4-125 
window frames 4-6, 4-12 to 4-13, 4-121 to 4-122 
window list 4-15, 4-74 
WindowList global variable 4-74 
Window Manager 4-3 to 4-129 
application-defined routine for 4-120 to 4-124 
and Control Manager 4-14 to 4-15, 5-3 
data structures in 4-65 to 4-74 
and Dialog Manager 4-13 to 4-14, 6-15 to 6-16 
Window Manager (continued) 
events generated by 2-9 
global variables 4-75 
port 4-74 
resources in 4-124 to 4-129 
routines in 4-74 to 4-119 
initializing 4-74 to 4-75 
low-level routines 4-116 to 4-119 
window origin 
changing 5-44 to 5-45, 5-48 to 5-52 
defined 5-45 
WindowPeek data type 4-20, 4-65 
window positioning constants 4-32 
WindowPtr data type 4-19, 4-65 
WindowRecord data type 4-19, 4-65, 4-69 
window records 4-19 to 4-20, 4-65 to 4-69 
window regions 4-12 to 4-13 
window resources 4-22, 4-25 to 4-27, 4-124 to 4-127 
windows 4-3 to 4-129 
activating 4-50 to 4-53 
active 4-6 
alert boxes and dialog boxes 
deactivating behind 6-64 to 6-66 
as types of 6-15 to 6-17 
closing 4-60 to 4-62, 4-103 to 4-106 
color in 4-20 to 4-21, 4-71 to 4-74 
content region 4-12 
controls in 4-14 to 4-15, 5-82 
creating 4-25 to 4-30, 4-75 to 4-85 
deallocating 4-61 to 4-62, 4-104 to 4-106 
defined 4-4 
displaying 4-86 to 4-91 
drawing content region 4-39 to 4-40 
events in 4-21, 4-22, 4-41 to 4-53 
grow image 4-57, 4-87 
hiding 4-62 to 4-64, 4-89 
inactive 4-6 to 4-7 
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maintaining update region of 4-106 to 4-109 
managing multiple 4-15 to 4-16, 4-23 to 4-25 
manipulating 
characteristics 4-109 to 4-112 
color 4-114 to 4-116 
on the desktop 4-112 to 4-114 
mouse-down events in 4-42 to 4-45 
moving 4-53, 4-94 to 4-99 
naming 4-85 to 4-86 
parts drawn by the Window Manager 4-12 to 4-13 
positioning 4-30 to 4-38 
regions in 4-12 to 4-13 
resizing 4-57 to 4-59 
responding to activate events in 2-50 to 2-55, 4-50 to 
4-53 
retrieving information 4-91 to 4-94 
scrolling 5-9 to 5-10, 5-43 to 5-70 
showing 4-62 to 4-64, 4-88 
sizing 4-99 to 4-101 
standard state 4-33, 4-53, 4-70 
structure region 4-12 
types of 4-8 to 4-10 
updating 2-47 to 2-50, 4-40 to 4-41, 4-48 to 4-50, 5-49 
to 5-52, 5-62 to 5-65 
user state 4-33, 4-53, 4-70 
window-manipulation conventions 4-21 
window resources, defining 4-25 to 4-27 
zooming 4-53 to 4-56, 4-101 to 4-103 
window state data record 4-33, 4-54, 4-70 to 4-71 
window types 4-8 to 4-11 
"WIND' resource type 4-22, 4-25 to 4-27, 4-124 to 4-127 
wristwatch cursor 2-63 
WStateData data type 4-33, 4-54, 4-70 to 4-71 


Z 


zoom box 4-6 

zoomDocProc window type 4-8 

zooming windows 4-53 to 4-56, 4-101 to 4-103 
zoomNoGrow window type 4-10 

zoom region 4-12 

ZoomWindow procedure 4-54, 4-57, 4-102 to 4-103 
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